zrule.h (10068B)
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 /** 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 /********************************************************************* 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