1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/vtzone.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,455 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +* Copyright (C) 2007-2013, International Business Machines Corporation and
1.7 +* others. All Rights Reserved.
1.8 +*******************************************************************************
1.9 +*/
1.10 +#ifndef VTZONE_H
1.11 +#define VTZONE_H
1.12 +
1.13 +#include "unicode/utypes.h"
1.14 +
1.15 +/**
1.16 + * \file
1.17 + * \brief C++ API: RFC2445 VTIMEZONE support
1.18 + */
1.19 +
1.20 +#if !UCONFIG_NO_FORMATTING
1.21 +
1.22 +#include "unicode/basictz.h"
1.23 +
1.24 +U_NAMESPACE_BEGIN
1.25 +
1.26 +class VTZWriter;
1.27 +class VTZReader;
1.28 +class UVector;
1.29 +
1.30 +/**
1.31 + * <code>VTimeZone</code> is a class implementing RFC2445 VTIMEZONE. You can create a
1.32 + * <code>VTimeZone</code> instance from a time zone ID supported by <code>TimeZone</code>.
1.33 + * With the <code>VTimeZone</code> instance created from the ID, you can write out the rule
1.34 + * in RFC2445 VTIMEZONE format. Also, you can create a <code>VTimeZone</code> instance
1.35 + * from RFC2445 VTIMEZONE data stream, which allows you to calculate time
1.36 + * zone offset by the rules defined by the data. Or, you can create a
1.37 + * <code>VTimeZone</code> from any other ICU <code>BasicTimeZone</code>.
1.38 + * <br><br>
1.39 + * Note: The consumer of this class reading or writing VTIMEZONE data is responsible to
1.40 + * decode or encode Non-ASCII text. Methods reading/writing VTIMEZONE data in this class
1.41 + * do nothing with MIME encoding.
1.42 + * @stable ICU 3.8
1.43 + */
1.44 +class U_I18N_API VTimeZone : public BasicTimeZone {
1.45 +public:
1.46 + /**
1.47 + * Copy constructor.
1.48 + * @param source The <code>VTimeZone</code> object to be copied.
1.49 + * @stable ICU 3.8
1.50 + */
1.51 + VTimeZone(const VTimeZone& source);
1.52 +
1.53 + /**
1.54 + * Destructor.
1.55 + * @stable ICU 3.8
1.56 + */
1.57 + virtual ~VTimeZone();
1.58 +
1.59 + /**
1.60 + * Assignment operator.
1.61 + * @param right The object to be copied.
1.62 + * @stable ICU 3.8
1.63 + */
1.64 + VTimeZone& operator=(const VTimeZone& right);
1.65 +
1.66 + /**
1.67 + * Return true if the given <code>TimeZone</code> objects are
1.68 + * semantically equal. Objects of different subclasses are considered unequal.
1.69 + * @param that The object to be compared with.
1.70 + * @return true if the given <code>TimeZone</code> objects are
1.71 + *semantically equal.
1.72 + * @stable ICU 3.8
1.73 + */
1.74 + virtual UBool operator==(const TimeZone& that) const;
1.75 +
1.76 + /**
1.77 + * Return true if the given <code>TimeZone</code> objects are
1.78 + * semantically unequal. Objects of different subclasses are considered unequal.
1.79 + * @param that The object to be compared with.
1.80 + * @return true if the given <code>TimeZone</code> objects are
1.81 + * semantically unequal.
1.82 + * @stable ICU 3.8
1.83 + */
1.84 + virtual UBool operator!=(const TimeZone& that) const;
1.85 +
1.86 + /**
1.87 + * Create a <code>VTimeZone</code> instance by the time zone ID.
1.88 + * @param ID The time zone ID, such as America/New_York
1.89 + * @return A <code>VTimeZone</code> object initialized by the time zone ID,
1.90 + * or NULL when the ID is unknown.
1.91 + * @stable ICU 3.8
1.92 + */
1.93 + static VTimeZone* createVTimeZoneByID(const UnicodeString& ID);
1.94 +
1.95 + /**
1.96 + * Create a <code>VTimeZone</code> instance using a basic time zone.
1.97 + * @param basicTZ The basic time zone instance
1.98 + * @param status Output param to filled in with a success or an error.
1.99 + * @return A <code>VTimeZone</code> object initialized by the basic time zone.
1.100 + * @stable ICU 4.6
1.101 + */
1.102 + static VTimeZone* createVTimeZoneFromBasicTimeZone(const BasicTimeZone& basicTZ,
1.103 + UErrorCode &status);
1.104 +
1.105 + /**
1.106 + * Create a <code>VTimeZone</code> instance by RFC2445 VTIMEZONE data
1.107 + *
1.108 + * @param vtzdata The string including VTIMEZONE data block
1.109 + * @param status Output param to filled in with a success or an error.
1.110 + * @return A <code>VTimeZone</code> initialized by the VTIMEZONE data or
1.111 + * NULL if failed to load the rule from the VTIMEZONE data.
1.112 + * @stable ICU 3.8
1.113 + */
1.114 + static VTimeZone* createVTimeZone(const UnicodeString& vtzdata, UErrorCode& status);
1.115 +
1.116 + /**
1.117 + * Gets the RFC2445 TZURL property value. When a <code>VTimeZone</code> instance was
1.118 + * created from VTIMEZONE data, the initial value is set by the TZURL property value
1.119 + * in the data. Otherwise, the initial value is not set.
1.120 + * @param url Receives the RFC2445 TZURL property value.
1.121 + * @return TRUE if TZURL attribute is available and value is set.
1.122 + * @stable ICU 3.8
1.123 + */
1.124 + UBool getTZURL(UnicodeString& url) const;
1.125 +
1.126 + /**
1.127 + * Sets the RFC2445 TZURL property value.
1.128 + * @param url The TZURL property value.
1.129 + * @stable ICU 3.8
1.130 + */
1.131 + void setTZURL(const UnicodeString& url);
1.132 +
1.133 + /**
1.134 + * Gets the RFC2445 LAST-MODIFIED property value. When a <code>VTimeZone</code> instance
1.135 + * was created from VTIMEZONE data, the initial value is set by the LAST-MODIFIED property
1.136 + * value in the data. Otherwise, the initial value is not set.
1.137 + * @param lastModified Receives the last modified date.
1.138 + * @return TRUE if lastModified attribute is available and value is set.
1.139 + * @stable ICU 3.8
1.140 + */
1.141 + UBool getLastModified(UDate& lastModified) const;
1.142 +
1.143 + /**
1.144 + * Sets the RFC2445 LAST-MODIFIED property value.
1.145 + * @param lastModified The LAST-MODIFIED date.
1.146 + * @stable ICU 3.8
1.147 + */
1.148 + void setLastModified(UDate lastModified);
1.149 +
1.150 + /**
1.151 + * Writes RFC2445 VTIMEZONE data for this time zone
1.152 + * @param result Output param to filled in with the VTIMEZONE data.
1.153 + * @param status Output param to filled in with a success or an error.
1.154 + * @stable ICU 3.8
1.155 + */
1.156 + void write(UnicodeString& result, UErrorCode& status) const;
1.157 +
1.158 + /**
1.159 + * Writes RFC2445 VTIMEZONE data for this time zone applicalbe
1.160 + * for dates after the specified start time.
1.161 + * @param start The start date.
1.162 + * @param result Output param to filled in with the VTIMEZONE data.
1.163 + * @param status Output param to filled in with a success or an error.
1.164 + * @stable ICU 3.8
1.165 + */
1.166 + void write(UDate start, UnicodeString& result, UErrorCode& status) const;
1.167 +
1.168 + /**
1.169 + * Writes RFC2445 VTIMEZONE data applicalbe for the specified date.
1.170 + * Some common iCalendar implementations can only handle a single time
1.171 + * zone property or a pair of standard and daylight time properties using
1.172 + * BYDAY rule with day of week (such as BYDAY=1SUN). This method produce
1.173 + * the VTIMEZONE data which can be handled these implementations. The rules
1.174 + * produced by this method can be used only for calculating time zone offset
1.175 + * around the specified date.
1.176 + * @param time The date used for rule extraction.
1.177 + * @param result Output param to filled in with the VTIMEZONE data.
1.178 + * @param status Output param to filled in with a success or an error.
1.179 + * @stable ICU 3.8
1.180 + */
1.181 + void writeSimple(UDate time, UnicodeString& result, UErrorCode& status) const;
1.182 +
1.183 + /**
1.184 + * Clones TimeZone objects polymorphically. Clients are responsible for deleting
1.185 + * the TimeZone object cloned.
1.186 + * @return A new copy of this TimeZone object.
1.187 + * @stable ICU 3.8
1.188 + */
1.189 + virtual TimeZone* clone(void) const;
1.190 +
1.191 + /**
1.192 + * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
1.193 + * to GMT to get local time in this time zone, taking daylight savings time into
1.194 + * account) as of a particular reference date. The reference date is used to determine
1.195 + * whether daylight savings time is in effect and needs to be figured into the offset
1.196 + * that is returned (in other words, what is the adjusted GMT offset in this time zone
1.197 + * at this particular date and time?). For the time zones produced by createTimeZone(),
1.198 + * the reference data is specified according to the Gregorian calendar, and the date
1.199 + * and time fields are local standard time.
1.200 + *
1.201 + * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
1.202 + * which returns both the raw and the DST offset for a given time. This method
1.203 + * is retained only for backward compatibility.
1.204 + *
1.205 + * @param era The reference date's era
1.206 + * @param year The reference date's year
1.207 + * @param month The reference date's month (0-based; 0 is January)
1.208 + * @param day The reference date's day-in-month (1-based)
1.209 + * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
1.210 + * @param millis The reference date's milliseconds in day, local standard time
1.211 + * @param status Output param to filled in with a success or an error.
1.212 + * @return The offset in milliseconds to add to GMT to get local time.
1.213 + * @stable ICU 3.8
1.214 + */
1.215 + virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
1.216 + uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const;
1.217 +
1.218 + /**
1.219 + * Gets the time zone offset, for current date, modified in case of
1.220 + * daylight savings. This is the offset to add *to* UTC to get local time.
1.221 + *
1.222 + * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
1.223 + * which returns both the raw and the DST offset for a given time. This method
1.224 + * is retained only for backward compatibility.
1.225 + *
1.226 + * @param era The reference date's era
1.227 + * @param year The reference date's year
1.228 + * @param month The reference date's month (0-based; 0 is January)
1.229 + * @param day The reference date's day-in-month (1-based)
1.230 + * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
1.231 + * @param millis The reference date's milliseconds in day, local standard time
1.232 + * @param monthLength The length of the given month in days.
1.233 + * @param status Output param to filled in with a success or an error.
1.234 + * @return The offset in milliseconds to add to GMT to get local time.
1.235 + * @stable ICU 3.8
1.236 + */
1.237 + virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
1.238 + uint8_t dayOfWeek, int32_t millis,
1.239 + int32_t monthLength, UErrorCode& status) const;
1.240 +
1.241 + /**
1.242 + * Returns the time zone raw and GMT offset for the given moment
1.243 + * in time. Upon return, local-millis = GMT-millis + rawOffset +
1.244 + * dstOffset. All computations are performed in the proleptic
1.245 + * Gregorian calendar. The default implementation in the TimeZone
1.246 + * class delegates to the 8-argument getOffset().
1.247 + *
1.248 + * @param date moment in time for which to return offsets, in
1.249 + * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
1.250 + * time or local wall time, depending on `local'.
1.251 + * @param local if true, `date' is local wall time; otherwise it
1.252 + * is in GMT time.
1.253 + * @param rawOffset output parameter to receive the raw offset, that
1.254 + * is, the offset not including DST adjustments
1.255 + * @param dstOffset output parameter to receive the DST offset,
1.256 + * that is, the offset to be added to `rawOffset' to obtain the
1.257 + * total offset between local and GMT time. If DST is not in
1.258 + * effect, this value is zero; otherwise it is a positive value,
1.259 + * typically one hour.
1.260 + * @param ec input-output error code
1.261 + * @stable ICU 3.8
1.262 + */
1.263 + virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
1.264 + int32_t& dstOffset, UErrorCode& ec) const;
1.265 +
1.266 + /**
1.267 + * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
1.268 + * to GMT to get local time, before taking daylight savings time into account).
1.269 + *
1.270 + * @param offsetMillis The new raw GMT offset for this time zone.
1.271 + * @stable ICU 3.8
1.272 + */
1.273 + virtual void setRawOffset(int32_t offsetMillis);
1.274 +
1.275 + /**
1.276 + * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
1.277 + * to GMT to get local time, before taking daylight savings time into account).
1.278 + *
1.279 + * @return The TimeZone's raw GMT offset.
1.280 + * @stable ICU 3.8
1.281 + */
1.282 + virtual int32_t getRawOffset(void) const;
1.283 +
1.284 + /**
1.285 + * Queries if this time zone uses daylight savings time.
1.286 + * @return true if this time zone uses daylight savings time,
1.287 + * false, otherwise.
1.288 + * @stable ICU 3.8
1.289 + */
1.290 + virtual UBool useDaylightTime(void) const;
1.291 +
1.292 + /**
1.293 + * Queries if the given date is in daylight savings time in
1.294 + * this time zone.
1.295 + * This method is wasteful since it creates a new GregorianCalendar and
1.296 + * deletes it each time it is called. This is a deprecated method
1.297 + * and provided only for Java compatibility.
1.298 + *
1.299 + * @param date the given UDate.
1.300 + * @param status Output param filled in with success/error code.
1.301 + * @return true if the given date is in daylight savings time,
1.302 + * false, otherwise.
1.303 + * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead.
1.304 + */
1.305 + virtual UBool inDaylightTime(UDate date, UErrorCode& status) const;
1.306 +
1.307 + /**
1.308 + * Returns true if this zone has the same rule and offset as another zone.
1.309 + * That is, if this zone differs only in ID, if at all.
1.310 + * @param other the <code>TimeZone</code> object to be compared with
1.311 + * @return true if the given zone is the same as this one,
1.312 + * with the possible exception of the ID
1.313 + * @stable ICU 3.8
1.314 + */
1.315 + virtual UBool hasSameRules(const TimeZone& other) const;
1.316 +
1.317 + /**
1.318 + * Gets the first time zone transition after the base time.
1.319 + * @param base The base time.
1.320 + * @param inclusive Whether the base time is inclusive or not.
1.321 + * @param result Receives the first transition after the base time.
1.322 + * @return TRUE if the transition is found.
1.323 + * @stable ICU 3.8
1.324 + */
1.325 + virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;
1.326 +
1.327 + /**
1.328 + * Gets the most recent time zone transition before the base time.
1.329 + * @param base The base time.
1.330 + * @param inclusive Whether the base time is inclusive or not.
1.331 + * @param result Receives the most recent transition before the base time.
1.332 + * @return TRUE if the transition is found.
1.333 + * @stable ICU 3.8
1.334 + */
1.335 + virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;
1.336 +
1.337 + /**
1.338 + * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
1.339 + * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
1.340 + * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value.
1.341 + * @param status Receives error status code.
1.342 + * @return The number of <code>TimeZoneRule</code>s representing time transitions.
1.343 + * @stable ICU 3.8
1.344 + */
1.345 + virtual int32_t countTransitionRules(UErrorCode& status) const;
1.346 +
1.347 + /**
1.348 + * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
1.349 + * which represent time transitions for this time zone. On successful return,
1.350 + * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
1.351 + * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
1.352 + * instances up to the size specified by trscount. The results are referencing the
1.353 + * rule instance held by this time zone instance. Therefore, after this time zone
1.354 + * is destructed, they are no longer available.
1.355 + * @param initial Receives the initial timezone rule
1.356 + * @param trsrules Receives the timezone transition rules
1.357 + * @param trscount On input, specify the size of the array 'transitions' receiving
1.358 + * the timezone transition rules. On output, actual number of
1.359 + * rules filled in the array will be set.
1.360 + * @param status Receives error status code.
1.361 + * @stable ICU 3.8
1.362 + */
1.363 + virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
1.364 + const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const;
1.365 +
1.366 +private:
1.367 + enum { DEFAULT_VTIMEZONE_LINES = 100 };
1.368 +
1.369 + /**
1.370 + * Default constructor.
1.371 + */
1.372 + VTimeZone();
1.373 + static VTimeZone* createVTimeZone(VTZReader* reader);
1.374 + void write(VTZWriter& writer, UErrorCode& status) const;
1.375 + void write(UDate start, VTZWriter& writer, UErrorCode& status) const;
1.376 + void writeSimple(UDate time, VTZWriter& writer, UErrorCode& status) const;
1.377 + void load(VTZReader& reader, UErrorCode& status);
1.378 + void parse(UErrorCode& status);
1.379 +
1.380 + void writeZone(VTZWriter& w, BasicTimeZone& basictz, UVector* customProps,
1.381 + UErrorCode& status) const;
1.382 +
1.383 + void writeHeaders(VTZWriter& w, UErrorCode& status) const;
1.384 + void writeFooter(VTZWriter& writer, UErrorCode& status) const;
1.385 +
1.386 + void writeZonePropsByTime(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
1.387 + int32_t fromOffset, int32_t toOffset, UDate time, UBool withRDATE,
1.388 + UErrorCode& status) const;
1.389 + void writeZonePropsByDOM(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
1.390 + int32_t fromOffset, int32_t toOffset,
1.391 + int32_t month, int32_t dayOfMonth, UDate startTime, UDate untilTime,
1.392 + UErrorCode& status) const;
1.393 + void writeZonePropsByDOW(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
1.394 + int32_t fromOffset, int32_t toOffset,
1.395 + int32_t month, int32_t weekInMonth, int32_t dayOfWeek,
1.396 + UDate startTime, UDate untilTime, UErrorCode& status) const;
1.397 + void writeZonePropsByDOW_GEQ_DOM(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
1.398 + int32_t fromOffset, int32_t toOffset,
1.399 + int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
1.400 + UDate startTime, UDate untilTime, UErrorCode& status) const;
1.401 + void writeZonePropsByDOW_GEQ_DOM_sub(VTZWriter& writer, int32_t month, int32_t dayOfMonth,
1.402 + int32_t dayOfWeek, int32_t numDays,
1.403 + UDate untilTime, int32_t fromOffset, UErrorCode& status) const;
1.404 + void writeZonePropsByDOW_LEQ_DOM(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
1.405 + int32_t fromOffset, int32_t toOffset,
1.406 + int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
1.407 + UDate startTime, UDate untilTime, UErrorCode& status) const;
1.408 + void writeFinalRule(VTZWriter& writer, UBool isDst, const AnnualTimeZoneRule* rule,
1.409 + int32_t fromRawOffset, int32_t fromDSTSavings,
1.410 + UDate startTime, UErrorCode& status) const;
1.411 +
1.412 + void beginZoneProps(VTZWriter& writer, UBool isDst, const UnicodeString& zonename,
1.413 + int32_t fromOffset, int32_t toOffset, UDate startTime, UErrorCode& status) const;
1.414 + void endZoneProps(VTZWriter& writer, UBool isDst, UErrorCode& status) const;
1.415 + void beginRRULE(VTZWriter& writer, int32_t month, UErrorCode& status) const;
1.416 + void appendUNTIL(VTZWriter& writer, const UnicodeString& until, UErrorCode& status) const;
1.417 +
1.418 + BasicTimeZone *tz;
1.419 + UVector *vtzlines;
1.420 + UnicodeString tzurl;
1.421 + UDate lastmod;
1.422 + UnicodeString olsonzid;
1.423 + UnicodeString icutzver;
1.424 +
1.425 +public:
1.426 + /**
1.427 + * Return the class ID for this class. This is useful only for comparing to
1.428 + * a return value from getDynamicClassID(). For example:
1.429 + * <pre>
1.430 + * . Base* polymorphic_pointer = createPolymorphicObject();
1.431 + * . if (polymorphic_pointer->getDynamicClassID() ==
1.432 + * . erived::getStaticClassID()) ...
1.433 + * </pre>
1.434 + * @return The class ID for all objects of this class.
1.435 + * @stable ICU 3.8
1.436 + */
1.437 + static UClassID U_EXPORT2 getStaticClassID(void);
1.438 +
1.439 + /**
1.440 + * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
1.441 + * method is to implement a simple version of RTTI, since not all C++
1.442 + * compilers support genuine RTTI. Polymorphic operator==() and clone()
1.443 + * methods call this method.
1.444 + *
1.445 + * @return The class ID for this object. All objects of a
1.446 + * given class have the same class ID. Objects of
1.447 + * other classes have different class IDs.
1.448 + * @stable ICU 3.8
1.449 + */
1.450 + virtual UClassID getDynamicClassID(void) const;
1.451 +};
1.452 +
1.453 +U_NAMESPACE_END
1.454 +
1.455 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.456 +
1.457 +#endif // VTZONE_H
1.458 +//eof
