icuSources/i18n/zrule.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 2009-2010, International Business Machines Corporation and         *
   4 * others. All Rights Reserved.                                                *
   5 *******************************************************************************
   6 */
   7 #ifndef __ZRULE_H
   8 #define __ZRULE_H
   9
  10 /**
  11  * \file
  12  * \brief C API: Time zone rule classes
  13  */
  14
  15 #include "unicode/utypes.h"
  16
  17 #if !UCONFIG_NO_FORMATTING
  18
  19 #ifndef UCNV_H
  20
  21 /**
  22  * A TimeZoneRule.  Use the zrule_* API to manipulate.  Create with
  23  * zrule_open*, and destroy with zrule_close.
  24  * @draft ICU 4.4
  25  */
  26 struct ZRule;
  27 typedef struct ZRule ZRule;
  28
  29 /**
  30  * An InitialTimeZoneRule.  Use the izrule_* API to manipulate.  Create with
  31  * izrule_open*, and destroy with izrule_close.
  32  * @draft ICU 4.4
  33  */
  34 struct IZRule;
  35 typedef struct IZRule IZRule;
  36
  37 /**
  38  * An AnnualTimeZoneRule.  Use the azrule_* API to manipulate.  Create with
  39  * azrule_open*, and destroy with azrule_close.
  40  * @draft ICU 4.4
  41  */
  42 struct AZRule;
  43 typedef struct AZRule AZRule;
  44
  45 #endif
  46
  47 /*********************************************************************
  48  * ZRule API
  49  *********************************************************************/
  50
  51 /**
  52  * Disposes of the storage used by a ZRule object.  This function should
  53  * be called exactly once for objects returned by zrule_open*.
  54  * @param set the object to dispose of
  55  * @draft ICU 4.4
  56  */
  57 U_DRAFT void U_EXPORT2
  58 zrule_close(ZRule* rule);
  59
  60 /**
  61  * Returns true if rule1 is identical to rule2
  62  * and vis versa.
  63  * @param rule1 to be checked for containment
  64  * @param rule2 to be checked for containment
  65  * @return true if the test condition is met
  66  * @draft ICU 4.4
  67  */
  68 U_DRAFT UBool U_EXPORT2
  69 zrule_equals(const ZRule* rule1, const ZRule* rule2);
  70
  71 /**
  72  * Fills in "name" with the name of this time zone.
  73  * @param rule, the Zrule to use
  74  * @param name  Receives the name of this time zone.
  75  * @param nameLength, length of the returned name
  76  * @draft ICU 4.4
  77  */
  78 U_DRAFT void U_EXPORT2
  79 zrule_getName(ZRule* rule, UChar* name, int32_t nameLength);
  80
  81 /**
  82  * Gets the standard time offset.
  83  * @param rule, the Zrule to use
  84  * @return  The standard time offset from UTC in milliseconds.
  85  * @draft ICU 4.4
  86  */
  87 U_DRAFT int32_t U_EXPORT2
  88 zrule_getRawOffset(ZRule* rule);
  89
  90 /**
  91  * Gets the amount of daylight saving delta time from the standard time.
  92  * @param rule, the Zrule to use
  93  * @return  The amount of daylight saving offset used by this rule
  94  *          in milliseconds.
  95  * @draft ICU 4.4
  96  */
  97 U_DRAFT int32_t U_EXPORT2
  98 zrule_getDSTSavings(ZRule* rule);
  99
 100 /**
 101  * Returns if this rule represents the same rule and offsets as another.
 102  * When two ZRule objects differ only its names, this method
 103  * returns true.
 104  * @param rule1 to be checked for containment
 105  * @param rule2 to be checked for containment
 106  * @return  true if the other <code>TimeZoneRule</code> is the same as this one.
 107  * @draft ICU 4.4
 108  */
 109 U_DRAFT UBool U_EXPORT2
 110 zrule_isEquivalentTo(ZRule* rule1,  ZRule* rule2);
 111
 112 /*********************************************************************
 113  * IZRule API
 114  *********************************************************************/
 115
 116 /**
 117  * Constructs an IZRule with the name, the GMT offset of its
 118  * standard time and the amount of daylight saving offset adjustment.
 119  * @param name          The time zone name.
 120  * @param nameLength    The length of the time zone name.
 121  * @param rawOffset     The UTC offset of its standard time in milliseconds.
 122  * @param dstSavings    The amount of daylight saving offset adjustment in milliseconds.
 123  *                      If this ia a rule for standard time, the value of this argument is 0.
 124  * @draft ICU 4.4
 125  */
 126 U_DRAFT IZRule* U_EXPORT2
 127 izrule_open(const UChar* name, int32_t nameLength, int32_t rawOffset, int32_t dstSavings);
 128
 129 /**
 130  * Disposes of the storage used by a IZRule object.  This function should
 131  * be called exactly once for objects returned by izrule_open*.
 132  * @param set the object to dispose of
 133  * @draft ICU 4.4
 134  */
 135 U_DRAFT void U_EXPORT2
 136 izrule_close(IZRule* rule);
 137
 138 /**
 139  * Returns a copy of this object.
 140  * @param rule the original IZRule
 141  * @return the newly allocated copy of the IZRule
 142  * @draft ICU 4.4
 143  */
 144 U_DRAFT IZRule* U_EXPORT2
 145 izrule_clone(IZRule *rule);
 146
 147 /**
 148  * Returns true if rule1 is identical to rule2
 149  * and vis versa.
 150  * @param rule1 to be checked for containment
 151  * @param rule2 to be checked for containment
 152  * @return true if the test condition is met
 153  * @draft ICU 4.4
 154  */
 155 U_DRAFT UBool U_EXPORT2
 156 izrule_equals(const IZRule* rule1, const IZRule* rule2);
 157
 158 /**
 159  * Fills in "name" with the name of this time zone.
 160  * @param rule, the IZrule to use
 161  * @param name  Receives the name of this time zone.
 162  * @param nameLength, length of the returned name
 163  * @draft ICU 4.4
 164  */
 165 U_DRAFT void U_EXPORT2
 166 izrule_getName(IZRule* rule, UChar* & name, int32_t & nameLength);
 167
 168 /**
 169  * Gets the standard time offset.
 170  * @param rule, the IZrule to use
 171  * @return  The standard time offset from UTC in milliseconds.
 172  * @draft ICU 4.4
 173  */
 174 U_DRAFT int32_t U_EXPORT2
 175 izrule_getRawOffset(IZRule* rule);
 176
 177 /**
 178  * Gets the amount of daylight saving delta time from the standard time.
 179  * @param rule, the IZrule to use
 180  * @return  The amount of daylight saving offset used by this rule
 181  *          in milliseconds.
 182  * @draft ICU 4.4
 183  */
 184 U_DRAFT int32_t U_EXPORT2
 185 izrule_getDSTSavings(IZRule* rule);
 186
 187 /**
 188  * Returns if this rule represents the same rule and offsets as another.
 189  * When two IZRule objects differ only its names, this method
 190  * returns true.
 191  * @param rule1 to be checked for containment
 192  * @param rule2 to be checked for containment
 193  * @return  true if the other <code>TimeZoneRule</code> is the same as this one.
 194  * @draft ICU 4.4
 195  */
 196 U_DRAFT UBool U_EXPORT2
 197 izrule_isEquivalentTo(IZRule* rule1,  IZRule* rule2);
 198
 199 /**
 200  * Gets the very first time when this rule takes effect.
 201  * @param rule              The IZrule to use
 202  * @param prevRawOffset     The standard time offset from UTC before this rule
 203  *                          takes effect in milliseconds.
 204  * @param prevDSTSavings    The amount of daylight saving offset from the
 205  *                          standard time.
 206  * @param result            Receives the very first time when this rule takes effect.
 207  * @return  true if the start time is available.  When false is returned, output parameter
 208  *          "result" is unchanged.
 209  * @draft ICU 4.4
 210  */
 211 U_DRAFT UBool U_EXPORT2
 212 izrule_getFirstStart(IZRule* rule, int32_t prevRawOffset, int32_t prevDSTSavings,
 213                     UDate& result);
 214
 215 /**
 216  * Gets the final time when this rule takes effect.
 217  * @param rule              The IZrule to use
 218  * @param prevRawOffset     The standard time offset from UTC before this rule
 219  *                          takes effect in milliseconds.
 220  * @param prevDSTSavings    The amount of daylight saving offset from the
 221  *                          standard time.
 222  * @param result            Receives the final time when this rule takes effect.
 223  * @return  true if the start time is available.  When false is returned, output parameter
 224  *          "result" is unchanged.
 225  * @draft ICU 4.4
 226  */
 227 U_DRAFT UBool U_EXPORT2
 228 izrule_getFinalStart(IZRule* rule, int32_t prevRawOffset, int32_t prevDSTSavings,
 229                     UDate& result);
 230
 231 /**
 232  * Gets the first time when this rule takes effect after the specified time.
 233  * @param rule              The IZrule to use
 234  * @param base              The first start time after this base time will be returned.
 235  * @param prevRawOffset     The standard time offset from UTC before this rule
 236  *                          takes effect in milliseconds.
 237  * @param prevDSTSavings    The amount of daylight saving offset from the
 238  *                          standard time.
 239  * @param inclusive         Whether the base time is inclusive or not.
 240  * @param result            Receives The first time when this rule takes effect after
 241  *                          the specified base time.
 242  * @return  true if the start time is available.  When false is returned, output parameter
 243  *          "result" is unchanged.
 244  * @draft ICU 4.4
 245  */
 246 U_DRAFT UBool U_EXPORT2
 247 izrule_getNextStart(IZRule* rule, UDate base, int32_t prevRawOffset,
 248                    int32_t prevDSTSavings, UBool inclusive, UDate& result);
 249
 250 /**
 251  * Gets the most recent time when this rule takes effect before the specified time.
 252  * @param rule              The IZrule to use
 253  * @param base              The most recent time before this base time will be returned.
 254  * @param prevRawOffset     The standard time offset from UTC before this rule
 255  *                          takes effect in milliseconds.
 256  * @param prevDSTSavings    The amount of daylight saving offset from the
 257  *                          standard time.
 258  * @param inclusive         Whether the base time is inclusive or not.
 259  * @param result            Receives The most recent time when this rule takes effect before
 260  *                          the specified base time.
 261  * @return  true if the start time is available.  When false is returned, output parameter
 262  *          "result" is unchanged.
 263  * @draft ICU 4.4
 264  */
 265 U_DRAFT UBool U_EXPORT2
 266 izrule_getPreviousStart(IZRule* rule, UDate base, int32_t prevRawOffset,
 267                        int32_t prevDSTSavings, UBool inclusive, UDate& result);
 268
 269
 270 /**
 271  * Return the class ID for this class. This is useful only for comparing to
 272  * a return value from getDynamicClassID(). For example:
 273  * <pre>
 274  * .   Base* polymorphic_pointer = createPolymorphicObject();
 275  * .   if (polymorphic_pointer->getDynamicClassID() ==
 276  * .       erived::getStaticClassID()) ...
 277  * </pre>
 278  * @param rule              The IZrule to use
 279  * @return          The class ID for all objects of this class.
 280  * @draft ICU 4.4
 281  */
 282 U_DRAFT UClassID U_EXPORT2
 283 izrule_getStaticClassID(IZRule* rule);
 284
 285 /**
 286  * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 287  * method is to implement a simple version of RTTI, since not all C++
 288  * compilers support genuine RTTI. Polymorphic operator==() and clone()
 289  * methods call this method.
 290  *
 291  * @param rule              The IZrule to use
 292  * @return          The class ID for this object. All objects of a
 293  *                  given class have the same class ID.  Objects of
 294  *                  other classes have different class IDs.
 295  * @draft ICU 4.4
 296  */
 297 U_DRAFT UClassID U_EXPORT2
 298 izrule_getDynamicClassID(IZRule* rule);
 299
 300 #endif
 301
 302 #endif