ICU 59.1  59.1
tzfmt.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 *******************************************************************************
5 * Copyright (C) 2011-2015, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 *******************************************************************************
8 */
9 #ifndef __TZFMT_H
10 #define __TZFMT_H
11 
17 #include "unicode/utypes.h"
18 
19 #if !UCONFIG_NO_FORMATTING
20 
21 #include "unicode/format.h"
22 #include "unicode/timezone.h"
23 #include "unicode/tznames.h"
24 
31 typedef enum UTimeZoneFormatStyle {
154 
190 
191  /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed for other .h declarations */
198 
221 
248 
250 
252 
253 class TimeZoneGenericNames;
254 class TZDBTimeZoneNames;
255 class UVector;
256 
273 public:
278  TimeZoneFormat(const TimeZoneFormat& other);
279 
284  virtual ~TimeZoneFormat();
285 
290  TimeZoneFormat& operator=(const TimeZoneFormat& other);
291 
300  virtual UBool operator==(const Format& other) const;
301 
308  virtual Format* clone() const;
309 
318  static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
319 
325  const TimeZoneNames* getTimeZoneNames() const;
326 
334  void adoptTimeZoneNames(TimeZoneNames *tznames);
335 
341  void setTimeZoneNames(const TimeZoneNames &tznames);
342 
350  UnicodeString& getGMTPattern(UnicodeString& pattern) const;
351 
360  void setGMTPattern(const UnicodeString& pattern, UErrorCode& status);
361 
370  UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, UnicodeString& pattern) const;
371 
380  void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString& pattern, UErrorCode& status);
381 
391  UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const;
392 
405  void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status);
406 
414  UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const;
415 
423  void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status);
424 
432  uint32_t getDefaultParseOptions(void) const;
433 
442  void setDefaultParseOptions(uint32_t flags);
443 
459  UnicodeString& formatOffsetISO8601Basic(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
460  UnicodeString& result, UErrorCode& status) const;
461 
477  UnicodeString& formatOffsetISO8601Extended(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
478  UnicodeString& result, UErrorCode& status) const;
479 
499  UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
500 
520  UnicodeString& formatOffsetShortLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
521 
522  using Format::format;
523 
537  virtual UnicodeString& format(UTimeZoneFormatStyle style, const TimeZone& tz, UDate date,
538  UnicodeString& name, UTimeZoneFormatTimeType* timeType = NULL) const;
539 
554  int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const;
555 
568  int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
569 
582  int32_t parseOffsetShortLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
583 
600  virtual TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
601  int32_t parseOptions, UTimeZoneFormatTimeType* timeType = NULL) const;
602 
618  TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
619  UTimeZoneFormatTimeType* timeType = NULL) const;
620 
621  /* ----------------------------------------------
622  * Format APIs
623  * ---------------------------------------------- */
624 
636  virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo,
637  FieldPosition& pos, UErrorCode& status) const;
638 
651  virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const;
652 
657  static UClassID U_EXPORT2 getStaticClassID(void);
658 
663  virtual UClassID getDynamicClassID() const;
664 
665 protected:
672  TimeZoneFormat(const Locale& locale, UErrorCode& status);
673 
674 private:
675  /* Locale of this object */
676  Locale fLocale;
677 
678  /* Stores the region (could be implicit default) */
679  char fTargetRegion[ULOC_COUNTRY_CAPACITY];
680 
681  /* TimeZoneNames object used by this formatter */
682  TimeZoneNames* fTimeZoneNames;
683 
684  /* TimeZoneGenericNames object used by this formatter - lazily instantiated */
685  TimeZoneGenericNames* fTimeZoneGenericNames;
686 
687  /* Localized GMT format pattern - e.g. "GMT{0}" */
688  UnicodeString fGMTPattern;
689 
690  /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */
691  UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT];
692 
693  /* Localized decimal digits used by Localized GMT format */
694  UChar32 fGMTOffsetDigits[10];
695 
696  /* Localized GMT zero format - e.g. "GMT" */
697  UnicodeString fGMTZeroFormat;
698 
699  /* Bit flags representing parse options */
700  uint32_t fDefParseOptionFlags;
701 
702  /* Constant parts of GMT format pattern, populated from localized GMT format pattern*/
703  UnicodeString fGMTPatternPrefix; /* Substring before {0} */
704  UnicodeString fGMTPatternSuffix; /* Substring after {0} */
705 
706  /* Compiled offset patterns generated from fGMTOffsetPatterns[] */
707  UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT];
708 
709  UBool fAbuttingOffsetHoursAndMinutes;
710 
711  /* TZDBTimeZoneNames object used for parsing */
712  TZDBTimeZoneNames* fTZDBTimeZoneNames;
713 
724  UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType,
725  UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const;
726 
735  UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const;
736 
742  const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const;
743 
749  const TZDBTimeZoneNames* getTZDBTimeZoneNames(UErrorCode& status) const;
750 
758  UnicodeString& formatExemplarLocation(const TimeZone& tz, UnicodeString& name) const;
759 
763  enum OffsetFields {
764  FIELDS_H,
765  FIELDS_HM,
766  FIELDS_HMS
767  };
768 
776  void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status);
777 
786  static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status);
787 
796  static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
797 
806  static UnicodeString& truncateOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
807 
818  static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity);
819 
830  UnicodeString& formatOffsetISO8601(int32_t offset, UBool isBasic, UBool useUtcIndicator,
831  UBool isShort, UBool ignoreSeconds, UnicodeString& result, UErrorCode& status) const;
832 
840  UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UBool isShort, UnicodeString& result, UErrorCode& status) const;
841 
856  int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly,
857  UBool* hasDigitOffset = NULL) const;
858 
866  void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const;
867 
880  int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos,
881  UBool isShort, UBool* hasDigitOffset) const;
882 
892  int32_t parseOffsetLocalizedGMTPattern(const UnicodeString& text, int32_t start,
893  UBool isShort, int32_t& parsedLen) const;
894 
903  int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool isShort, int32_t& parsedLen) const;
904 
916  int32_t parseOffsetFieldsWithPattern(const UnicodeString& text, int32_t start,
917  UVector* patternItems, UBool forceSingleHourDigit, int32_t& hour, int32_t& min, int32_t& sec) const;
918 
926  int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const;
927 
935  int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const;
936 
945  int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, char16_t separator,
946  int32_t& parsedLen) const;
947 
962  int32_t parseOffsetFieldWithLocalizedDigits(const UnicodeString& text, int32_t start,
963  uint8_t minDigits, uint8_t maxDigits, uint16_t minVal, uint16_t maxVal, int32_t& parsedLen) const;
964 
974  int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const;
975 
985  static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, char16_t sep,
986  OffsetFields minFields, OffsetFields maxFields, UnicodeString& result);
987 
1000  static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos,
1001  OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth);
1002 
1015  static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, char16_t sep,
1016  OffsetFields minFields, OffsetFields maxFields);
1017 
1024  static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result);
1025 
1031  void initGMTOffsetPatterns(UErrorCode& status);
1032 
1039  void checkAbuttingHoursAndMinutes();
1040 
1046  TimeZone* createTimeZoneForOffset(int32_t offset) const;
1047 
1053  static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType);
1054 
1063  UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const;
1064 
1065 
1073  UnicodeString& parseZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1074 
1082  UnicodeString& parseShortZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1083 
1091  UnicodeString& parseExemplarLocation(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1092 };
1093 
1095 
1096 #endif /* !UCONFIG_NO_FORMATTING */
1097 #endif
When a time zone display name is not found within a set of display names used for the specified style...
Definition: tzfmt.h:238
Base class for all formats.
Definition: format.h:96
UTimeZoneFormatGMTOffsetPatternType
Constants for GMT offset pattern types.
Definition: tzfmt.h:159
Negative offset with hours and minutes fields.
Definition: tzfmt.h:174
TimeZoneFormat supports time zone display name formatting and parsing.
Definition: tzfmt.h:272
Fixed width ISO 8601 local time difference (basic format) or the UTC indicator.
Definition: tzfmt.h:88
ISO 8601 local time difference (basic format) with optional seconds field.
Definition: tzfmt.h:109
UTimeZoneFormatParseOption
Constants for parse option flags, used for specifying optional parse behavior.
Definition: tzfmt.h:226
Negative offset with hours field.
Definition: tzfmt.h:189
UTimeZoneFormatTimeType
Constants for time types used by TimeZoneFormat APIs for receiving time type (standard time...
Definition: tzfmt.h:204
UnicodeString & format(const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
Formats an object to produce a string.
Generic location format, such as "United States Time (New York)", "Italy Time".
Definition: tzfmt.h:36
ISO 8601 local time difference (extended format) with optional seconds field, or the UTC indicator...
Definition: tzfmt.h:130
Short localized GMT offset format, such as "GMT-5", "UTC+1:30" This style is equivalent to the LDML d...
Definition: tzfmt.h:67
Positive offset with hours field.
Definition: tzfmt.h:184
C++ API: TimeZone object.
double UDate
Date and Time data type.
Definition: utypes.h:203
#define ULOC_COUNTRY_CAPACITY
Useful constant for the maximum size of the country part of a locale ID (including the terminating NU...
Definition: uloc.h:258
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:93
Negative offset with hours, minutes and seconds fields.
Definition: tzfmt.h:179
virtual Format * clone() const =0
Clone this object polymorphically.
TimeZone represents a time zone offset, and also figures out daylight savings.
Definition: timezone.h:131
C++ API: Base class for all formats.
#define U_CDECL_BEGIN
This is used to begin a declaration of a library private ICU C API.
Definition: umachine.h:84
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside...
Definition: utypes.h:360
Fixed width ISO 8601 local time difference (basic format).
Definition: tzfmt.h:95
Exemplar location, such as "Los Angeles" and "Paris".
Definition: tzfmt.h:152
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:131
MatchInfoCollection represents a collection of time zone name matches used by TimeZoneNames#find.
Definition: tznames.h:310
Fixed width ISO 8601 local time difference (extended format) or the UTC indicator.
Definition: tzfmt.h:116
Daylight saving time.
Definition: tzfmt.h:219
Positive offset with hours and minutes fields.
Definition: tzfmt.h:164
TimeZoneNames is an abstract class representing the time zone display name data model defined by UTS#...
Definition: tznames.h:129
Short ISO 8601 locale time difference (basic format).
Definition: tzfmt.h:81
C++ API: TimeZoneNames.
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:396
#define NULL
Define NULL if necessary, to nullptr for C++ and to ((void *)0) for C.
Definition: utypes.h:188
virtual UClassID getDynamicClassID() const
ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
ISO 8601 local time difference (basic format) with optional seconds field, or the UTC indicator...
Definition: tzfmt.h:102
UTimeZoneFormatStyle
Constants for time zone display format style used by format/parse APIs in TimeZoneFormat.
Definition: tzfmt.h:31
Time Zone ID, such as "America/Los_Angeles".
Definition: tzfmt.h:142
Specific short format, such as "EST", "PDT".
Definition: tzfmt.h:56
#define U_CDECL_END
This is used to end a declaration of a library private ICU C API.
Definition: umachine.h:85
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:132
Positive offset with hours, minutes and seconds fields.
Definition: tzfmt.h:169
Short Time Zone ID (BCP 47 Unicode location extension, time zone type value), such as "uslax"...
Definition: tzfmt.h:147
Generic long non-location format, such as "Eastern Time".
Definition: tzfmt.h:41
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:396
FieldPosition is a simple class used by Format and its subclasses to identify fields in formatted out...
Definition: fieldpos.h:108
ParsePosition is a simple class used by Format and its subclasses to keep track of the current positi...
Definition: parsepos.h:49
virtual UBool operator==(const Format &other) const =0
Return true if the given Format objects are semantically equal.
Standard time.
Definition: tzfmt.h:214
virtual void parseObject(const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const =0
Parse a string to produce an object.
Fixed width ISO 8601 local time difference (extended format).
Definition: tzfmt.h:123
Basic definitions for ICU, for both C and C++ APIs.
Format & operator=(const Format &)
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
Specific long format, such as "Eastern Standard Time".
Definition: tzfmt.h:51
Formattable objects can be passed to the Format class or its subclasses for formatting.
Definition: fmtable.h:68
UTimeZoneNameType
Constants for time zone display name types.
Definition: tznames.h:29
Short ISO 8601 local time difference (basic format) or the UTC indicator.
Definition: tzfmt.h:74
ISO 8601 local time difference (extended format) with optional seconds field.
Definition: tzfmt.h:137
When parsing a time zone display name in UTZFMT_STYLE_SPECIFIC_SHORT, look for the IANA tz database c...
Definition: tzfmt.h:246
Localized GMT offset format, such as "GMT-05:00", "UTC+0100".
Definition: tzfmt.h:61
Number of UTimeZoneFormatGMTOffsetPatternType types.
Definition: tzfmt.h:196
Generic short non-location format, such as "ET".
Definition: tzfmt.h:46
int8_t UBool
The ICU boolean type.
Definition: umachine.h:236
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:188