DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Implementation

Mercurial (31ec81b5d7bb)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
/*
*******************************************************************************
* Copyright (C) 2009-2011, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/

/**
* \file
* \brief C API: RFC2445 VTIMEZONE support
*
* <p>This is a C wrapper around the C++ VTimeZone class.</p>
*/

#ifndef __VZONE_H
#define __VZONE_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "ztrans.h"

#ifndef UCNV_H
struct VZone;
/**
 * A UnicodeSet.  Use the vzone_* API to manipulate.  Create with
 * vzone_open*, and destroy with vzone_close.
 */
typedef struct VZone VZone;
#endif

/*********************************************************************
 * VZone API
 *********************************************************************/

/**
 * Creates a vzone from the given time zone ID.
 * @param ID The time zone ID, such as America/New_York
 * @param idLength, length of the ID parameter
 * @return A vzone object initialized by the time zone ID,
 * or NULL when the ID is unknown.
 */
U_CAPI VZone* U_EXPORT2
vzone_openID(const UChar* ID, int32_t idLength);

/**
 * Create a vzone instance by RFC2445 VTIMEZONE data
 * @param vtzdata The string including VTIMEZONE data block
 * @param vtzdataLength, length of the vtzdata
 * @param status Output param to filled in with a success or an error.
 * @return A vzone initialized by the VTIMEZONE data or
 * NULL if failed to load the rule from the VTIMEZONE data.
 */
U_CAPI VZone* U_EXPORT2
vzone_openData(const UChar* vtzdata, int32_t vtzdataLength, UErrorCode& status);

/**
 * Disposes of the storage used by a VZone object.  This function should
 * be called exactly once for objects returned by vzone_open*.
 * @param set the object to dispose of
 */
U_CAPI void U_EXPORT2
vzone_close(VZone* zone);

/**
 * Returns a copy of this object.
 * @param zone the original vzone
 * @return the newly allocated copy of the vzone
 */
U_CAPI VZone* U_EXPORT2
vzone_clone(const VZone *zone);

/**
 * Returns true if zone1 is identical to zone2
 * and vis versa.
 * @param zone1 to be checked for containment
 * @param zone2 to be checked for containment
 * @return true if the test condition is met
 */
U_CAPI UBool U_EXPORT2
vzone_equals(const VZone* zone1, const VZone* zone2);

/**
 * Gets the RFC2445 TZURL property value.  When a vzone instance was
 * created from VTIMEZONE data, the initial value is set by the TZURL 
 * property value in the data.  Otherwise, the initial value is not set.
 * @param zone, the vzone to use
 * @param url Receives the RFC2445 TZURL property value.
 * @param urlLength, length of the url
 * @return TRUE if TZURL attribute is available and value is set.
 */
U_CAPI UBool U_EXPORT2
vzone_getTZURL(VZone* zone, UChar* & url, int32_t & urlLength);

/**
 * Sets the RFC2445 TZURL property value.
 * @param zone, the vzone to use
 * @param url The TZURL property value.
 * @param urlLength, length of the url
 */
U_CAPI void U_EXPORT2
vzone_setTZURL(VZone* zone, UChar* url, int32_t urlLength);

/**
 * Gets the RFC2445 LAST-MODIFIED property value.  When a vzone instance
 * was created from VTIMEZONE data, the initial value is set by the 
 * LAST-MODIFIED property value in the data.  Otherwise, the initial value 
 * is not set.
 * @param zone, the vzone to use
 * @param lastModified Receives the last modified date.
 * @return TRUE if lastModified attribute is available and value is set.
 */
U_CAPI UBool U_EXPORT2
vzone_getLastModified(VZone* zone, UDate& lastModified);

/**
 * Sets the RFC2445 LAST-MODIFIED property value.
 * @param zone, the vzone to use
 * @param lastModified The LAST-MODIFIED date.
 */
U_CAPI void U_EXPORT2
vzone_setLastModified(VZone* zone, UDate lastModified);

/**
 * Writes RFC2445 VTIMEZONE data for this time zone
 * @param zone, the vzone to use
 * @param result Output param to filled in with the VTIMEZONE data.
 * @param resultLength, length of the result output
 * @param status Output param to filled in with a success or an error.
 */
U_CAPI void U_EXPORT2
vzone_write(VZone* zone, UChar* & result, int32_t & resultLength, UErrorCode& status);

/**
 * Writes RFC2445 VTIMEZONE data for this time zone applicalbe
 * for dates after the specified start time.
 * @param zone, the vzone to use
 * @param start The start date.
 * @param result Output param to filled in with the VTIMEZONE data.
 * @param resultLength, length of the result output
 * @param status Output param to filled in with a success or an error.
 */
U_CAPI void U_EXPORT2
vzone_writeFromStart(VZone* zone, UDate start, UChar* & result, int32_t & resultLength, UErrorCode& status);

/**
 * Writes RFC2445 VTIMEZONE data applicalbe for the specified date.
 * Some common iCalendar implementations can only handle a single time
 * zone property or a pair of standard and daylight time properties using
 * BYDAY rule with day of week (such as BYDAY=1SUN).  This method produce
 * the VTIMEZONE data which can be handled these implementations.  The rules
 * produced by this method can be used only for calculating time zone offset
 * around the specified date.
 * @param zone, the vzone to use
 * @param time The date used for rule extraction.
 * @param result Output param to filled in with the VTIMEZONE data.
 * @param status Output param to filled in with a success or an error.
 */
U_CAPI void U_EXPORT2
vzone_writeSimple(VZone* zone, UDate time, UChar* & result, int32_t & resultLength, UErrorCode& status);

/**
 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
 * to GMT to get local time in this time zone, taking daylight savings time into
 * account) as of a particular reference date.  The reference date is used to determine
 * whether daylight savings time is in effect and needs to be figured into the offset
 * that is returned (in other words, what is the adjusted GMT offset in this time zone
 * at this particular date and time?).  For the time zones produced by createTimeZone(),
 * the reference data is specified according to the Gregorian calendar, and the date
 * and time fields are local standard time.
 *
 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
 * which returns both the raw and the DST offset for a given time. This method
 * is retained only for backward compatibility.
 *
 * @param zone, the vzone to use
 * @param era        The reference date's era
 * @param year       The reference date's year
 * @param month      The reference date's month (0-based; 0 is January)
 * @param day        The reference date's day-in-month (1-based)
 * @param dayOfWeek  The reference date's day-of-week (1-based; 1 is Sunday)
 * @param millis     The reference date's milliseconds in day, local standard time
 * @param status     Output param to filled in with a success or an error.
 * @return           The offset in milliseconds to add to GMT to get local time.
 */
U_CAPI int32_t U_EXPORT2
vzone_getOffset(VZone* zone, uint8_t era, int32_t year, int32_t month, int32_t day,
                uint8_t dayOfWeek, int32_t millis, UErrorCode& status);

/**
 * Gets the time zone offset, for current date, modified in case of
 * daylight savings. This is the offset to add *to* UTC to get local time.
 *
 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
 * which returns both the raw and the DST offset for a given time. This method
 * is retained only for backward compatibility.
 *
 * @param zone, the vzone to use
 * @param era        The reference date's era
 * @param year       The reference date's year
 * @param month      The reference date's month (0-based; 0 is January)
 * @param day        The reference date's day-in-month (1-based)
 * @param dayOfWeek  The reference date's day-of-week (1-based; 1 is Sunday)
 * @param millis     The reference date's milliseconds in day, local standard time
 * @param monthLength The length of the given month in days.
 * @param status     Output param to filled in with a success or an error.
 * @return           The offset in milliseconds to add to GMT to get local time.
 */
U_CAPI int32_t U_EXPORT2
vzone_getOffset2(VZone* zone, uint8_t era, int32_t year, int32_t month, int32_t day,
                uint8_t dayOfWeek, int32_t millis,
                int32_t monthLength, UErrorCode& status);

/**
 * Returns the time zone raw and GMT offset for the given moment
 * in time.  Upon return, local-millis = GMT-millis + rawOffset +
 * dstOffset.  All computations are performed in the proleptic
 * Gregorian calendar.  The default implementation in the TimeZone
 * class delegates to the 8-argument getOffset().
 *
 * @param zone, the vzone to use
 * @param date moment in time for which to return offsets, in
 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
 * time or local wall time, depending on `local'.
 * @param local if true, `date' is local wall time; otherwise it
 * is in GMT time.
 * @param rawOffset output parameter to receive the raw offset, that
 * is, the offset not including DST adjustments
 * @param dstOffset output parameter to receive the DST offset,
 * that is, the offset to be added to `rawOffset' to obtain the
 * total offset between local and GMT time. If DST is not in
 * effect, this value is zero; otherwise it is a positive value,
 * typically one hour.
 * @param ec input-output error code
 */
U_CAPI void U_EXPORT2
vzone_getOffset3(VZone* zone, UDate date, UBool local, int32_t& rawOffset,
                int32_t& dstOffset, UErrorCode& ec);

/**
 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
 * to GMT to get local time, before taking daylight savings time into account).
 *
 * @param zone, the vzone to use
 * @param offsetMillis  The new raw GMT offset for this time zone.
 */
U_CAPI void U_EXPORT2
vzone_setRawOffset(VZone* zone, int32_t offsetMillis);

/**
 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
 * to GMT to get local time, before taking daylight savings time into account).
 *
 * @param zone, the vzone to use
 * @return   The TimeZone's raw GMT offset.
 */
U_CAPI int32_t U_EXPORT2
vzone_getRawOffset(VZone* zone);

/**
 * Queries if this time zone uses daylight savings time.
 * @param zone, the vzone to use
 * @return true if this time zone uses daylight savings time,
 * false, otherwise.
 */
U_CAPI UBool U_EXPORT2
vzone_useDaylightTime(VZone* zone);

/**
 * Queries if the given date is in daylight savings time in
 * this time zone.
 * This method is wasteful since it creates a new GregorianCalendar and
 * deletes it each time it is called. This is a deprecated method
 * and provided only for Java compatibility.
 *
 * @param zone, the vzone to use
 * @param date the given UDate.
 * @param status Output param filled in with success/error code.
 * @return true if the given date is in daylight savings time,
 * false, otherwise.
 */
U_INTERNAL UBool U_EXPORT2
vzone_inDaylightTime(VZone* zone, UDate date, UErrorCode& status);

/**
 * Returns true if this zone has the same rule and offset as another zone.
 * That is, if this zone differs only in ID, if at all.
 * @param zone, the vzone to use
 * @param other the <code>TimeZone</code> object to be compared with
 * @return true if the given zone is the same as this one,
 * with the possible exception of the ID
 */
U_CAPI UBool U_EXPORT2
vzone_hasSameRules(VZone* zone, const VZone* other);

/**
 * Gets the first time zone transition after the base time.
 * @param zone, the vzone to use
 * @param base      The base time.
 * @param inclusive Whether the base time is inclusive or not.
 * @param result    Receives the first transition after the base time.
 * @return  TRUE if the transition is found.
 */
U_CAPI UBool U_EXPORT2
vzone_getNextTransition(VZone* zone, UDate base, UBool inclusive, ZTrans* result);

/**
 * Gets the most recent time zone transition before the base time.
 * @param zone, the vzone to use
 * @param base      The base time.
 * @param inclusive Whether the base time is inclusive or not.
 * @param result    Receives the most recent transition before the base time.
 * @return  TRUE if the transition is found.
 */
U_CAPI UBool U_EXPORT2
vzone_getPreviousTransition(VZone* zone, UDate base, UBool inclusive, ZTrans* result);

/**
 * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
 * <code>InitialTimeZoneRule</code>.  The return value range is 0 or any positive value.
 * @param zone, the vzone to use     
 * @param status    Receives error status code.
 * @return The number of <code>TimeZoneRule</code>s representing time transitions.
 */
U_CAPI int32_t U_EXPORT2
vzone_countTransitionRules(VZone* zone, UErrorCode& status);

/**
 * Return the class ID for this class. This is useful only for comparing to
 * a return value from getDynamicClassID(). For example:
 * <pre>
 * .   Base* polymorphic_pointer = createPolymorphicObject();
 * .   if (polymorphic_pointer->getDynamicClassID() ==
 * .       erived::getStaticClassID()) ...
 * </pre>
 * @param zone, the vzone to use
 * @return          The class ID for all objects of this class.
 */
U_CAPI UClassID U_EXPORT2
vzone_getStaticClassID(VZone* zone);

/**
 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 * method is to implement a simple version of RTTI, since not all C++
 * compilers support genuine RTTI. Polymorphic operator==() and clone()
 * methods call this method.
 *
 * @param zone, the vzone to use
 * @return          The class ID for this object. All objects of a
 *                  given class have the same class ID.  Objects of
 *                  other classes have different class IDs.
 */
U_CAPI UClassID U_EXPORT2
vzone_getDynamicClassID(VZone* zone);

#endif // __VZONE_H

#endif