1 // © 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 284