icuSources/i18n/zrule.h

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