icuSources/i18n/zrule.h

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