source/i18n/zrule.h

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