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 */ 25struct ZRule; 26typedef 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 */ 32struct IZRule; 33typedef 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 */ 39struct AZRule; 40typedef 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 */ 53U_CAPI void U_EXPORT2 54zrule_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 */ 63U_CAPI UBool U_EXPORT2 64zrule_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 */ 72U_CAPI void U_EXPORT2 73zrule_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 */ 80U_CAPI int32_t U_EXPORT2 81zrule_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 */ 89U_CAPI int32_t U_EXPORT2 90zrule_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 */ 100U_CAPI UBool U_EXPORT2 101zrule_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 */ 116U_CAPI IZRule* U_EXPORT2 117izrule_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 */ 124U_CAPI void U_EXPORT2 125izrule_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 */ 132U_CAPI IZRule* U_EXPORT2 133izrule_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 */ 142U_CAPI UBool U_EXPORT2 143izrule_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 */ 151U_CAPI void U_EXPORT2 152izrule_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 */ 159U_CAPI int32_t U_EXPORT2 160izrule_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 */ 168U_CAPI int32_t U_EXPORT2 169izrule_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 */ 179U_CAPI UBool U_EXPORT2 180izrule_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 */ 193U_CAPI UBool U_EXPORT2 194izrule_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 */ 208U_CAPI UBool U_EXPORT2 209izrule_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 */ 226U_CAPI UBool U_EXPORT2 227izrule_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 */ 244U_CAPI UBool U_EXPORT2 245izrule_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 */ 260U_CAPI UClassID U_EXPORT2 261izrule_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 */ 274U_CAPI UClassID U_EXPORT2 275izrule_getDynamicClassID(IZRule* rule); 276 277#endif 278 279#endif 280