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