ICU 75.1 75.1

timezone.h
Go to the documentation of this file.
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*************************************************************************
4 * Copyright (c) 1997-2016, International Business Machines Corporation
5 * and others. All Rights Reserved.
6 **************************************************************************
7 *
8 * File TIMEZONE.H
9 *
10 * Modification History:
11 *
12 * Date Name Description
13 * 04/21/97 aliu Overhauled header.
14 * 07/09/97 helena Changed createInstance to createDefault.
15 * 08/06/97 aliu Removed dependency on internal header for Hashtable.
16 * 08/10/98 stephen Changed getDisplayName() API conventions to match
17 * 08/19/98 stephen Changed createTimeZone() to never return 0
18 * 09/02/98 stephen Sync to JDK 1.2 8/31
19 * - Added getOffset(... monthlen ...)
20 * - Added hasSameRules()
21 * 09/15/98 stephen Added getStaticClassID
22 * 12/03/99 aliu Moved data out of static table into icudata.dll.
23 * Hashtable replaced by new static data structures.
24 * 12/14/99 aliu Made GMT public.
25 * 08/15/01 grhoten Made GMT private and added the getGMT() function
26 **************************************************************************
27 */
28
29 #ifndef TIMEZONE_H
30 #define TIMEZONE_H
31
32 #include "unicode/utypes.h"
33
34 #if U_SHOW_CPLUSPLUS_API
35
41 #if !UCONFIG_NO_FORMATTING
42
43 #include "unicode/uobject.h"
44 #include "unicode/unistr.h"
45 #include "unicode/ures.h"
46 #include "unicode/ucal.h"
47
48 U_NAMESPACE_BEGIN
49
50 class StringEnumeration;
51
133 class U_I18N_API TimeZone : public UObject {
134 public:
138 virtual ~TimeZone();
139
152 static const TimeZone& U_EXPORT2 getUnknown();
153
166 static const TimeZone* U_EXPORT2 getGMT();
167
179 static TimeZone* U_EXPORT2 createTimeZone(const UnicodeString& ID);
180
196 static StringEnumeration* U_EXPORT2 createTimeZoneIDEnumeration(
197 USystemTimeZoneType zoneType,
198 const char* region,
199 const int32_t* rawOffset,
200 UErrorCode& ec);
201
202 #ifndef U_HIDE_DEPRECATED_API
210 static StringEnumeration* U_EXPORT2 createEnumeration();
211 #endif // U_HIDE_DEPRECATED_API
212
221 static StringEnumeration* U_EXPORT2 createEnumeration(UErrorCode& status);
222
223 #ifndef U_HIDE_DEPRECATED_API
241 static StringEnumeration* U_EXPORT2 createEnumeration(int32_t rawOffset);
242 #endif // U_HIDE_DEPRECATED_API
243
262 static StringEnumeration* U_EXPORT2 createEnumerationForRawOffset(int32_t rawOffset, UErrorCode& status);
263
264 #ifndef U_HIDE_DEPRECATED_API
275 static StringEnumeration* U_EXPORT2 createEnumeration(const char* region);
276 #endif // U_HIDE_DEPRECATED_API
277
289 static StringEnumeration* U_EXPORT2 createEnumerationForRegion(const char* region, UErrorCode& status);
290
305 static int32_t U_EXPORT2 countEquivalentIDs(const UnicodeString& id);
306
326 static const UnicodeString U_EXPORT2 getEquivalentID(const UnicodeString& id,
327 int32_t index);
328
352 static TimeZone* U_EXPORT2 detectHostTimeZone();
353
367 static TimeZone* U_EXPORT2 createDefault();
368
369 #ifndef U_HIDE_INTERNAL_API
379 static TimeZone* U_EXPORT2 forLocaleOrDefault(const Locale& locale);
380 #endif /* U_HIDE_INTERNAL_API */
381
391 static void U_EXPORT2 adoptDefault(TimeZone* zone);
392
393 #ifndef U_HIDE_SYSTEM_API
402 static void U_EXPORT2 setDefault(const TimeZone& zone);
403 #endif /* U_HIDE_SYSTEM_API */
404
411 static const char* U_EXPORT2 getTZDataVersion(UErrorCode& status);
412
426 static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id,
427 UnicodeString& canonicalID, UErrorCode& status);
428
444 static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id,
445 UnicodeString& canonicalID, UBool& isSystemID, UErrorCode& status);
446
447
448 #ifndef U_HIDE_DRAFT_API
474 static UnicodeString& U_EXPORT2 getIanaID(const UnicodeString&id, UnicodeString& ianaID,
475 UErrorCode& status);
476 #endif // U_HIDE_DRAFT_API
477
500 static UnicodeString& U_EXPORT2 getWindowsID(const UnicodeString& id,
501 UnicodeString& winid, UErrorCode& status);
502
529 static UnicodeString& U_EXPORT2 getIDForWindowsID(const UnicodeString& winid, const char* region,
530 UnicodeString& id, UErrorCode& status);
531
541 virtual bool operator==(const TimeZone& that) const;
542
552 bool operator!=(const TimeZone& that) const {return !operator==(that);}
553
578 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
579 uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const = 0;
580
601 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
602 uint8_t dayOfWeek, int32_t milliseconds,
603 int32_t monthLength, UErrorCode& status) const = 0;
604
628 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
629 int32_t& dstOffset, UErrorCode& ec) const;
630
638 virtual void setRawOffset(int32_t offsetMillis) = 0;
639
647 virtual int32_t getRawOffset() const = 0;
648
656 UnicodeString& getID(UnicodeString& ID) const;
657
671 void setID(const UnicodeString& ID);
672
677 enum EDisplayType {
682 SHORT = 1,
687 LONG,
692 SHORT_GENERIC,
697 LONG_GENERIC,
703 SHORT_GMT,
709 LONG_GMT,
715 SHORT_COMMONLY_USED,
721 GENERIC_LOCATION
722 };
723
735 UnicodeString& getDisplayName(UnicodeString& result) const;
736
750 UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) const;
751
764 UnicodeString& getDisplayName(UBool inDaylight, EDisplayType style, UnicodeString& result) const;
765
780 UnicodeString& getDisplayName(UBool inDaylight, EDisplayType style, const Locale& locale, UnicodeString& result) const;
781
816 virtual UBool useDaylightTime() const = 0;
817
818 #ifndef U_FORCE_HIDE_DEPRECATED_API
832 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const = 0;
833 #endif // U_FORCE_HIDE_DEPRECATED_API
834
843 virtual UBool hasSameRules(const TimeZone& other) const;
844
852 virtual TimeZone* clone() const = 0;
853
860 static UClassID U_EXPORT2 getStaticClassID();
861
873 virtual UClassID getDynamicClassID() const override = 0;
874
890 virtual int32_t getDSTSavings() const;
891
909 static int32_t U_EXPORT2 getRegion(const UnicodeString& id,
910 char *region, int32_t capacity, UErrorCode& status);
911
912 protected:
913
918 TimeZone();
919
925 TimeZone(const UnicodeString &id);
926
932 TimeZone(const TimeZone& source);
933
939 TimeZone& operator=(const TimeZone& right);
940
941 #ifndef U_HIDE_INTERNAL_API
951 static UResourceBundle* loadRule(const UResourceBundle* top, const UnicodeString& ruleid, UResourceBundle* oldbundle, UErrorCode&status);
952 #endif /* U_HIDE_INTERNAL_API */
953
954 private:
955 friend class ZoneMeta;
956
957
958 static TimeZone* createCustomTimeZone(const UnicodeString&); // Creates a time zone based on the string.
959
968 static const char16_t* findID(const UnicodeString& id);
969
978 static const char16_t* dereferOlsonLink(const UnicodeString& id);
979
986 static const char16_t* getRegion(const UnicodeString& id);
987
988 public:
989 #ifndef U_HIDE_INTERNAL_API
998 static const char16_t* getRegion(const UnicodeString& id, UErrorCode& status);
999 #endif /* U_HIDE_INTERNAL_API */
1000
1001 private:
1012 static UBool parseCustomID(const UnicodeString& id, int32_t& sign, int32_t& hour,
1013 int32_t& minute, int32_t& second);
1014
1025 static UnicodeString& getCustomID(const UnicodeString& id, UnicodeString& normalized,
1026 UErrorCode& status);
1027
1037 static UnicodeString& formatCustomID(int32_t hour, int32_t min, int32_t sec,
1038 UBool negative, UnicodeString& id);
1039
1040 UnicodeString fID; // this time zone's ID
1041
1042 friend class TZEnumeration;
1043 };
1044
1045
1046 // -------------------------------------
1047
1048 inline UnicodeString&
1049 TimeZone::getID(UnicodeString& ID) const
1050 {
1051 ID = fID;
1052 return ID;
1053 }
1054
1055 // -------------------------------------
1056
1057 inline void
1058 TimeZone::setID(const UnicodeString& ID)
1059 {
1060 fID = ID;
1061 }
1062 U_NAMESPACE_END
1063
1064 #endif /* #if !UCONFIG_NO_FORMATTING */
1065
1066 #endif /* U_SHOW_CPLUSPLUS_API */
1067
1068 #endif //_TIMEZONE
1069 //eof
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
icu::StringEnumeration
Base class for 'pure' C++ implementations of uenum api.
Definition: strenum.h:61
icu::TimeZone
TimeZone represents a time zone offset, and also figures out daylight savings.
Definition: timezone.h:133
icu::TimeZone::getStaticClassID
static UClassID getStaticClassID()
Return the class ID for this class.
icu::TimeZone::EDisplayType
EDisplayType
Enum for use with getDisplayName.
Definition: timezone.h:677
icu::TimeZone::SHORT_COMMONLY_USED
@ SHORT_COMMONLY_USED
Selector for short display name derived from the time zone's fallback name.
Definition: timezone.h:715
icu::TimeZone::LONG_GMT
@ LONG_GMT
Selector for long display name derived from time zone offset.
Definition: timezone.h:709
icu::TimeZone::SHORT_GENERIC
@ SHORT_GENERIC
Selector for short generic display name.
Definition: timezone.h:692
icu::TimeZone::LONG
@ LONG
Selector for long display name.
Definition: timezone.h:687
icu::TimeZone::SHORT_GMT
@ SHORT_GMT
Selector for short display name derived from time zone offset.
Definition: timezone.h:703
icu::TimeZone::LONG_GENERIC
@ LONG_GENERIC
Selector for long generic display name.
Definition: timezone.h:697
icu::TimeZone::getIDForWindowsID
static UnicodeString & getIDForWindowsID(const UnicodeString &winid, const char *region, UnicodeString &id, UErrorCode &status)
Converts a Windows time zone ID to an equivalent system time zone ID for a region.
icu::TimeZone::getRegion
static int32_t getRegion(const UnicodeString &id, char *region, int32_t capacity, UErrorCode &status)
Gets the region code associated with the given system time zone ID.
icu::TimeZone::getDynamicClassID
virtual UClassID getDynamicClassID() const override=0
Returns a unique class ID POLYMORPHICALLY.
icu::TimeZone::setRawOffset
virtual void setRawOffset(int32_t offsetMillis)=0
Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add to GMT to get local time,...
icu::TimeZone::clone
virtual TimeZone * clone() const =0
Clones TimeZone objects polymorphically.
icu::TimeZone::setDefault
static void setDefault(const TimeZone &zone)
Same as adoptDefault(), except that the TimeZone object passed in is NOT adopted; the caller remains ...
icu::TimeZone::operator==
virtual bool operator==(const TimeZone &that) const
Returns true if the two TimeZones are equal.
icu::TimeZone::getWindowsID
static UnicodeString & getWindowsID(const UnicodeString &id, UnicodeString &winid, UErrorCode &status)
Converts a system time zone ID to an equivalent Windows time zone ID.
icu::TimeZone::createEnumerationForRawOffset
static StringEnumeration * createEnumerationForRawOffset(int32_t rawOffset, UErrorCode &status)
Returns an enumeration over time zone IDs with a given raw offset from GMT.
icu::TimeZone::getDisplayName
UnicodeString & getDisplayName(UBool inDaylight, EDisplayType style, UnicodeString &result) const
Returns a name of this time zone suitable for presentation to the user in the default locale.
icu::TimeZone::createTimeZone
static TimeZone * createTimeZone(const UnicodeString &ID)
Creates a TimeZone for the given ID.
icu::TimeZone::useDaylightTime
virtual UBool useDaylightTime() const =0
Queries if this time zone uses daylight savings time.
icu::TimeZone::getDisplayName
UnicodeString & getDisplayName(const Locale &locale, UnicodeString &result) const
Returns a name of this time zone suitable for presentation to the user in the specified locale.
icu::TimeZone::TimeZone
TimeZone(const TimeZone &source)
Copy constructor.
icu::TimeZone::getTZDataVersion
static const char * getTZDataVersion(UErrorCode &status)
Returns the timezone data version currently used by ICU.
icu::TimeZone::getOffset
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 =0
Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add to GMT to get loc...
icu::TimeZone::detectHostTimeZone
static TimeZone * detectHostTimeZone()
Creates an instance of TimeZone detected from the current host system configuration.
icu::TimeZone::TimeZone
TimeZone(const UnicodeString &id)
Construct a TimeZone with a given ID.
icu::TimeZone::loadRule
static UResourceBundle * loadRule(const UResourceBundle *top, const UnicodeString &ruleid, UResourceBundle *oldbundle, UErrorCode &status)
Utility function.
icu::TimeZone::createTimeZoneIDEnumeration
static StringEnumeration * createTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char *region, const int32_t *rawOffset, UErrorCode &ec)
Returns an enumeration over system time zone IDs with the given filter conditions.
icu::TimeZone::operator=
TimeZone & operator=(const TimeZone &right)
Default assignment operator.
icu::TimeZone::getDisplayName
UnicodeString & getDisplayName(UnicodeString &result) const
Returns a name of this time zone suitable for presentation to the user in the default locale.
icu::TimeZone::forLocaleOrDefault
static TimeZone * forLocaleOrDefault(const Locale &locale)
If the locale contains the timezone keyword, creates a copy of that TimeZone.
icu::TimeZone::getRegion
static const char16_t * getRegion(const UnicodeString &id, UErrorCode &status)
Returns the region code associated with the given zone, or nullptr if the zone is not known.
icu::TimeZone::hasSameRules
virtual UBool hasSameRules(const TimeZone &other) const
Returns true if this zone has the same rule and offset as another zone.
icu::TimeZone::getDisplayName
UnicodeString & getDisplayName(UBool inDaylight, EDisplayType style, const Locale &locale, UnicodeString &result) const
Returns a name of this time zone suitable for presentation to the user in the specified locale.
icu::TimeZone::countEquivalentIDs
static int32_t countEquivalentIDs(const UnicodeString &id)
Returns the number of IDs in the equivalency group that includes the given ID.
icu::TimeZone::adoptDefault
static void adoptDefault(TimeZone *zone)
Sets the default time zone (i.e., what's returned by createDefault()) to be the specified time zone.
icu::TimeZone::TimeZone
TimeZone()
Default constructor.
icu::TimeZone::getCanonicalID
static UnicodeString & getCanonicalID(const UnicodeString &id, UnicodeString &canonicalID, UErrorCode &status)
Returns the canonical system timezone ID or the normalized custom time zone ID for the given time zon...
icu::TimeZone::createEnumeration
static StringEnumeration * createEnumeration(UErrorCode &status)
Returns an enumeration over all recognized time zone IDs.
icu::TimeZone::createEnumeration
static StringEnumeration * createEnumeration(int32_t rawOffset)
Returns an enumeration over time zone IDs with a given raw offset from GMT.
icu::TimeZone::operator!=
bool operator!=(const TimeZone &that) const
Returns true if the two TimeZones are NOT equal; that is, if operator==() returns false.
Definition: timezone.h:552
icu::TimeZone::getOffset
virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, uint8_t dayOfWeek, int32_t milliseconds, int32_t monthLength, UErrorCode &status) const =0
Gets the time zone offset, for current date, modified in case of daylight savings.
icu::TimeZone::createEnumeration
static StringEnumeration * createEnumeration(const char *region)
Returns an enumeration over time zone IDs associated with the given region.
icu::TimeZone::createEnumeration
static StringEnumeration * createEnumeration()
Returns an enumeration over all recognized time zone IDs.
icu::TimeZone::getIanaID
static UnicodeString & getIanaID(const UnicodeString &id, UnicodeString &ianaID, UErrorCode &status)
Returns the preferred time zone ID in the IANA time zone database for the given time zone ID.
icu::TimeZone::getRawOffset
virtual int32_t getRawOffset() const =0
Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add to GMT to get local ti...
icu::TimeZone::getEquivalentID
static const UnicodeString getEquivalentID(const UnicodeString &id, int32_t index)
Returns an ID in the equivalency group that includes the given ID.
icu::TimeZone::getCanonicalID
static UnicodeString & getCanonicalID(const UnicodeString &id, UnicodeString &canonicalID, UBool &isSystemID, UErrorCode &status)
Returns the canonical system time zone ID or the normalized custom time zone ID for the given time zo...
icu::TimeZone::inDaylightTime
virtual UBool inDaylightTime(UDate date, UErrorCode &status) const =0
Queries if the given date is in daylight savings time in this time zone.
icu::TimeZone::getUnknown
static const TimeZone & getUnknown()
Returns the "unknown" time zone.
icu::TimeZone::~TimeZone
virtual ~TimeZone()
icu::TimeZone::createEnumerationForRegion
static StringEnumeration * createEnumerationForRegion(const char *region, UErrorCode &status)
Returns an enumeration over time zone IDs associated with the given region.
icu::TimeZone::getGMT
static const TimeZone * getGMT()
The GMT (=UTC) time zone has a raw offset of zero and does not use daylight savings time.
icu::TimeZone::getDSTSavings
virtual int32_t getDSTSavings() const
Returns the amount of time to be added to local standard time to get local wall clock time.
icu::TimeZone::getOffset
virtual void getOffset(UDate date, UBool local, int32_t &rawOffset, int32_t &dstOffset, UErrorCode &ec) const
Returns the time zone raw and GMT offset for the given moment in time.
icu::TimeZone::createDefault
static TimeZone * createDefault()
Creates a new copy of the default TimeZone for this host.
icu::UObject
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:223
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
icu::operator==
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
ucal.h
C API: Calendar.
USystemTimeZoneType
USystemTimeZoneType
System time zone type constants used by filtering zones in ucal_openTimeZoneIDEnumeration.
Definition: ucal.h:579
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
unistr.h
C++ API: Unicode String.
uobject.h
C++ API: Common ICU base class UObject.
UClassID
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:96
ures.h
C API: Resource Bundle.
UResourceBundle
struct UResourceBundle UResourceBundle
Definition: ures.h:63
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
U_I18N_API
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside.
Definition: utypes.h:301
UDate
double UDate
Date and Time data type.
Definition: utypes.h:203