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.

Mercurial (cdf352f02ac4)

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 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 2007-2013, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
#ifndef VTZONE_H
#define VTZONE_H

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

/**
 * \file 
 * \brief C++ API: RFC2445 VTIMEZONE support
 */

#if !UCONFIG_NO_FORMATTING

#include "unicode/basictz.h"

U_NAMESPACE_BEGIN

class VTZWriter;
class VTZReader;
class UVector;

/**
 * <code>VTimeZone</code> is a class implementing RFC2445 VTIMEZONE.  You can create a
 * <code>VTimeZone</code> instance from a time zone ID supported by <code>TimeZone</code>.
 * With the <code>VTimeZone</code> instance created from the ID, you can write out the rule
 * in RFC2445 VTIMEZONE format.  Also, you can create a <code>VTimeZone</code> instance
 * from RFC2445 VTIMEZONE data stream, which allows you to calculate time
 * zone offset by the rules defined by the data. Or, you can create a
 * <code>VTimeZone</code> from any other ICU <code>BasicTimeZone</code>.
 * <br><br>
 * Note: The consumer of this class reading or writing VTIMEZONE data is responsible to
 * decode or encode Non-ASCII text.  Methods reading/writing VTIMEZONE data in this class
 * do nothing with MIME encoding.
 * @stable ICU 3.8
 */
class U_I18N_API VTimeZone : public BasicTimeZone {
public:
    /**
     * Copy constructor.
     * @param source    The <code>VTimeZone</code> object to be copied.
     * @stable ICU 3.8
     */
    VTimeZone(const VTimeZone& source);

    /**
     * Destructor.
     * @stable ICU 3.8
     */
    virtual ~VTimeZone();

    /**
     * Assignment operator.
     * @param right The object to be copied.
     * @stable ICU 3.8
     */
    VTimeZone& operator=(const VTimeZone& right);

    /**
     * Return true if the given <code>TimeZone</code> objects are
     * semantically equal. Objects of different subclasses are considered unequal.
     * @param that  The object to be compared with.
     * @return  true if the given <code>TimeZone</code> objects are
      *semantically equal.
     * @stable ICU 3.8
     */
    virtual UBool operator==(const TimeZone& that) const;

    /**
     * Return true if the given <code>TimeZone</code> objects are
     * semantically unequal. Objects of different subclasses are considered unequal.
     * @param that  The object to be compared with.
     * @return  true if the given <code>TimeZone</code> objects are
     * semantically unequal.
     * @stable ICU 3.8
     */
    virtual UBool operator!=(const TimeZone& that) const;

    /**
     * Create a <code>VTimeZone</code> instance by the time zone ID.
     * @param ID The time zone ID, such as America/New_York
     * @return A <code>VTimeZone</code> object initialized by the time zone ID,
     * or NULL when the ID is unknown.
     * @stable ICU 3.8
     */
    static VTimeZone* createVTimeZoneByID(const UnicodeString& ID);

    /**
     * Create a <code>VTimeZone</code> instance using a basic time zone.
     * @param basicTZ The basic time zone instance
     * @param status Output param to filled in with a success or an error.
     * @return A <code>VTimeZone</code> object initialized by the basic time zone.
     * @stable ICU 4.6
     */
    static VTimeZone* createVTimeZoneFromBasicTimeZone(const BasicTimeZone& basicTZ,
                                                       UErrorCode &status);

    /**
     * Create a <code>VTimeZone</code> instance by RFC2445 VTIMEZONE data
     * 
     * @param vtzdata The string including VTIMEZONE data block
     * @param status Output param to filled in with a success or an error.
     * @return A <code>VTimeZone</code> initialized by the VTIMEZONE data or
     * NULL if failed to load the rule from the VTIMEZONE data.
     * @stable ICU 3.8
     */
    static VTimeZone* createVTimeZone(const UnicodeString& vtzdata, UErrorCode& status);

    /**
     * Gets the RFC2445 TZURL property value.  When a <code>VTimeZone</code> 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 url Receives the RFC2445 TZURL property value.
     * @return TRUE if TZURL attribute is available and value is set.
     * @stable ICU 3.8
     */
    UBool getTZURL(UnicodeString& url) const;

    /**
     * Sets the RFC2445 TZURL property value.
     * @param url The TZURL property value.
     * @stable ICU 3.8
     */
    void setTZURL(const UnicodeString& url);

    /**
     * Gets the RFC2445 LAST-MODIFIED property value.  When a <code>VTimeZone</code> 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 lastModified Receives the last modified date.
     * @return TRUE if lastModified attribute is available and value is set.
     * @stable ICU 3.8
     */
    UBool getLastModified(UDate& lastModified) const;

    /**
     * Sets the RFC2445 LAST-MODIFIED property value.
     * @param lastModified The LAST-MODIFIED date.
     * @stable ICU 3.8
     */
    void setLastModified(UDate lastModified);

    /**
     * Writes RFC2445 VTIMEZONE data for this time zone
     * @param result Output param to filled in with the VTIMEZONE data.
     * @param status Output param to filled in with a success or an error.
     * @stable ICU 3.8
     */
    void write(UnicodeString& result, UErrorCode& status) const;

    /**
     * Writes RFC2445 VTIMEZONE data for this time zone applicalbe
     * for dates after the specified start time.
     * @param start The start date.
     * @param result Output param to filled in with the VTIMEZONE data.
     * @param status Output param to filled in with a success or an error.
     * @stable ICU 3.8
     */
    void write(UDate start, UnicodeString& result, UErrorCode& status) const;

    /**
     * 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 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.
     * @stable ICU 3.8
     */
    void writeSimple(UDate time, UnicodeString& result, UErrorCode& status) const;

    /**
     * Clones TimeZone objects polymorphically. Clients are responsible for deleting
     * the TimeZone object cloned.
     * @return   A new copy of this TimeZone object.
     * @stable ICU 3.8
     */
    virtual VTimeZone* clone() const;

    /**
     * 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 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.
     * @stable ICU 3.8
     */
    virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
                              uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const;

    /**
     * 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 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.
     * @stable ICU 3.8
     */
    virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
                           uint8_t dayOfWeek, int32_t millis,
                           int32_t monthLength, UErrorCode& status) const;

    /**
     * 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 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
     * @stable ICU 3.8
     */
    virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
                           int32_t& dstOffset, UErrorCode& ec) const;

    /**
     * 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 offsetMillis  The new raw GMT offset for this time zone.
     * @stable ICU 3.8
     */
    virtual void setRawOffset(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).
     *
     * @return   The TimeZone's raw GMT offset.
     * @stable ICU 3.8
     */
    virtual int32_t getRawOffset(void) const;

    /**
     * Queries if this time zone uses daylight savings time.
     * @return true if this time zone uses daylight savings time,
     * false, otherwise.
     * @stable ICU 3.8
     */
    virtual UBool useDaylightTime(void) const;

#ifndef U_FORCE_HIDE_DEPRECATED_API
    /**
     * 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 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.
     * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead.
     */
    virtual UBool inDaylightTime(UDate date, UErrorCode& status) const;
#endif  // U_FORCE_HIDE_DEPRECATED_API

    /**
     * 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 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
     * @stable ICU 3.8
     */
    virtual UBool hasSameRules(const TimeZone& other) const;

    /**
     * Gets the first time zone transition after the base time.
     * @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.
     * @stable ICU 3.8
     */
    virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;

    /**
     * Gets the most recent time zone transition before the base time.
     * @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.
     * @stable ICU 3.8
     */
    virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;

    /**
     * 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 status    Receives error status code.
     * @return The number of <code>TimeZoneRule</code>s representing time transitions.
     * @stable ICU 3.8
     */
    virtual int32_t countTransitionRules(UErrorCode& status) const;

    /**
     * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
     * which represent time transitions for this time zone.  On successful return,
     * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
     * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
     * instances up to the size specified by trscount.  The results are referencing the
     * rule instance held by this time zone instance.  Therefore, after this time zone
     * is destructed, they are no longer available.
     * @param initial       Receives the initial timezone rule
     * @param trsrules      Receives the timezone transition rules
     * @param trscount      On input, specify the size of the array 'transitions' receiving
     *                      the timezone transition rules.  On output, actual number of
     *                      rules filled in the array will be set.
     * @param status        Receives error status code.
     * @stable ICU 3.8
     */
    virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
        const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const;

private:
    enum { DEFAULT_VTIMEZONE_LINES = 100 };

    /**
     * Default constructor.
     */
    VTimeZone();
    static VTimeZone* createVTimeZone(VTZReader* reader);
    void write(VTZWriter& writer, UErrorCode& status) const;
    void write(UDate start, VTZWriter& writer, UErrorCode& status) const;
    void writeSimple(UDate time, VTZWriter& writer, UErrorCode& status) const;
    void load(VTZReader& reader, UErrorCode& status);
    void parse(UErrorCode& status);

    void writeZone(VTZWriter& w, BasicTimeZone& basictz, UVector* customProps,
        UErrorCode& status) const;

    void writeHeaders(VTZWriter& w, UErrorCode& status) const;
    void writeFooter(VTZWriter& writer, UErrorCode& status) const;

    void writeZonePropsByTime(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
                              int32_t fromOffset, int32_t toOffset, UDate time, UBool withRDATE,
                              UErrorCode& status) const;
    void writeZonePropsByDOM(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
                             int32_t fromOffset, int32_t toOffset,
                             int32_t month, int32_t dayOfMonth, UDate startTime, UDate untilTime,
                             UErrorCode& status) const;
    void writeZonePropsByDOW(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
                             int32_t fromOffset, int32_t toOffset,
                             int32_t month, int32_t weekInMonth, int32_t dayOfWeek,
                             UDate startTime, UDate untilTime, UErrorCode& status) const;
    void writeZonePropsByDOW_GEQ_DOM(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
                                     int32_t fromOffset, int32_t toOffset,
                                     int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
                                     UDate startTime, UDate untilTime, UErrorCode& status) const;
    void writeZonePropsByDOW_GEQ_DOM_sub(VTZWriter& writer, int32_t month, int32_t dayOfMonth,
                                         int32_t dayOfWeek, int32_t numDays,
                                         UDate untilTime, int32_t fromOffset, UErrorCode& status) const;
    void writeZonePropsByDOW_LEQ_DOM(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
                                     int32_t fromOffset, int32_t toOffset,
                                     int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
                                     UDate startTime, UDate untilTime, UErrorCode& status) const;
    void writeFinalRule(VTZWriter& writer, UBool isDst, const AnnualTimeZoneRule* rule,
                        int32_t fromRawOffset, int32_t fromDSTSavings,
                        UDate startTime, UErrorCode& status) const;

    void beginZoneProps(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
                        int32_t fromOffset, int32_t toOffset, UDate startTime, UErrorCode& status) const;
    void endZoneProps(VTZWriter& writer, UBool isDst, UErrorCode& status) const;
    void beginRRULE(VTZWriter& writer, int32_t month, UErrorCode& status) const;
    void appendUNTIL(VTZWriter& writer, const UnicodeString& until, UErrorCode& status) const;

    BasicTimeZone   *tz;
    UVector         *vtzlines;
    UnicodeString   tzurl;
    UDate           lastmod;
    UnicodeString   olsonzid;
    UnicodeString   icutzver;

public:
    /**
     * 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>
     * @return          The class ID for all objects of this class.
     * @stable ICU 3.8
     */
    static UClassID U_EXPORT2 getStaticClassID(void);

    /**
     * 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.
     *
     * @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.
     * @stable ICU 3.8
     */
    virtual UClassID getDynamicClassID(void) const;
};

U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif /* U_SHOW_CPLUSPLUS_API */

#endif // VTZONE_H
//eof