ICU 54.1  54.1
tzfmt.h
Go to the documentation of this file.
1 /*
2 *******************************************************************************
3 * Copyright (C) 2011-2014, International Business Machines Corporation and
4 * others. All Rights Reserved.
5 *******************************************************************************
6 */
7 #ifndef __TZFMT_H
8 #define __TZFMT_H
9 
15 #include "unicode/utypes.h"
16 
17 #if !UCONFIG_NO_FORMATTING
18 
19 #include "unicode/format.h"
20 #include "unicode/timezone.h"
21 #include "unicode/tznames.h"
22 
29 typedef enum UTimeZoneFormatStyle {
152 
188 
189  /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed for other .h declarations */
196 
219 
237 #ifndef U_HIDE_DRAFT_API
238  ,
247 #endif /* U_HIDE_DRAFT_API */
249 
251 
253 
254 class TimeZoneGenericNames;
255 class TZDBTimeZoneNames;
256 class UVector;
257 
274 public:
279  TimeZoneFormat(const TimeZoneFormat& other);
280 
285  virtual ~TimeZoneFormat();
286 
291  TimeZoneFormat& operator=(const TimeZoneFormat& other);
292 
301  virtual UBool operator==(const Format& other) const;
302 
309  virtual Format* clone() const;
310 
319  static TimeZoneFormat* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
320 
326  const TimeZoneNames* getTimeZoneNames() const;
327 
335  void adoptTimeZoneNames(TimeZoneNames *tznames);
336 
342  void setTimeZoneNames(const TimeZoneNames &tznames);
343 
351  UnicodeString& getGMTPattern(UnicodeString& pattern) const;
352 
361  void setGMTPattern(const UnicodeString& pattern, UErrorCode& status);
362 
371  UnicodeString& getGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, UnicodeString& pattern) const;
372 
381  void setGMTOffsetPattern(UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString& pattern, UErrorCode& status);
382 
392  UnicodeString& getGMTOffsetDigits(UnicodeString& digits) const;
393 
406  void setGMTOffsetDigits(const UnicodeString& digits, UErrorCode& status);
407 
415  UnicodeString& getGMTZeroFormat(UnicodeString& gmtZeroFormat) const;
416 
424  void setGMTZeroFormat(const UnicodeString& gmtZeroFormat, UErrorCode& status);
425 
433  uint32_t getDefaultParseOptions(void) const;
434 
443  void setDefaultParseOptions(uint32_t flags);
444 
460  UnicodeString& formatOffsetISO8601Basic(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
461  UnicodeString& result, UErrorCode& status) const;
462 
478  UnicodeString& formatOffsetISO8601Extended(int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds,
479  UnicodeString& result, UErrorCode& status) const;
480 
500  UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
501 
521  UnicodeString& formatOffsetShortLocalizedGMT(int32_t offset, UnicodeString& result, UErrorCode& status) const;
522 
523  using Format::format;
524 
538  virtual UnicodeString& format(UTimeZoneFormatStyle style, const TimeZone& tz, UDate date,
539  UnicodeString& name, UTimeZoneFormatTimeType* timeType = NULL) const;
540 
555  int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos) const;
556 
569  int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
570 
583  int32_t parseOffsetShortLocalizedGMT(const UnicodeString& text, ParsePosition& pos) const;
584 
601  virtual TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
602  int32_t parseOptions, UTimeZoneFormatTimeType* timeType = NULL) const;
603 
619  TimeZone* parse(UTimeZoneFormatStyle style, const UnicodeString& text, ParsePosition& pos,
620  UTimeZoneFormatTimeType* timeType = NULL) const;
621 
622  /* ----------------------------------------------
623  * Format APIs
624  * ---------------------------------------------- */
625 
637  virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo,
638  FieldPosition& pos, UErrorCode& status) const;
639 
652  virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const;
653 
658  static UClassID U_EXPORT2 getStaticClassID(void);
659 
664  virtual UClassID getDynamicClassID() const;
665 
666 protected:
673  TimeZoneFormat(const Locale& locale, UErrorCode& status);
674 
675 private:
676  /* Locale of this object */
677  Locale fLocale;
678 
679  /* Stores the region (could be implicit default) */
680  char fTargetRegion[ULOC_COUNTRY_CAPACITY];
681 
682  /* TimeZoneNames object used by this formatter */
683  TimeZoneNames* fTimeZoneNames;
684 
685  /* TimeZoneGenericNames object used by this formatter - lazily instantiated */
686  TimeZoneGenericNames* fTimeZoneGenericNames;
687 
688  /* Localized GMT format pattern - e.g. "GMT{0}" */
689  UnicodeString fGMTPattern;
690 
691  /* Array of offset patterns used by Localized GMT format - e.g. "+HH:mm" */
692  UnicodeString fGMTOffsetPatterns[UTZFMT_PAT_COUNT];
693 
694  /* Localized decimal digits used by Localized GMT format */
695  UChar32 fGMTOffsetDigits[10];
696 
697  /* Localized GMT zero format - e.g. "GMT" */
698  UnicodeString fGMTZeroFormat;
699 
700  /* Bit flags representing parse options */
701  uint32_t fDefParseOptionFlags;
702 
703  /* Constant parts of GMT format pattern, populated from localized GMT format pattern*/
704  UnicodeString fGMTPatternPrefix; /* Substring before {0} */
705  UnicodeString fGMTPatternSuffix; /* Substring after {0} */
706 
707  /* Compiled offset patterns generated from fGMTOffsetPatterns[] */
708  UVector* fGMTOffsetPatternItems[UTZFMT_PAT_COUNT];
709 
710  UBool fAbuttingOffsetHoursAndMinutes;
711 
712  /* TZDBTimeZoneNames object used for parsing */
713  TZDBTimeZoneNames* fTZDBTimeZoneNames;
714 
725  UnicodeString& formatSpecific(const TimeZone& tz, UTimeZoneNameType stdType, UTimeZoneNameType dstType,
726  UDate date, UnicodeString& name, UTimeZoneFormatTimeType *timeType) const;
727 
736  UnicodeString& formatGeneric(const TimeZone& tz, int32_t genType, UDate date, UnicodeString& name) const;
737 
743  const TimeZoneGenericNames* getTimeZoneGenericNames(UErrorCode& status) const;
744 
750  const TZDBTimeZoneNames* getTZDBTimeZoneNames(UErrorCode& status) const;
751 
759  UnicodeString& formatExemplarLocation(const TimeZone& tz, UnicodeString& name) const;
760 
764  enum OffsetFields {
765  FIELDS_H,
766  FIELDS_HM,
767  FIELDS_HMS
768  };
769 
777  void initGMTPattern(const UnicodeString& gmtPattern, UErrorCode& status);
778 
787  static UVector* parseOffsetPattern(const UnicodeString& pattern, OffsetFields required, UErrorCode& status);
788 
797  static UnicodeString& expandOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
798 
807  static UnicodeString& truncateOffsetPattern(const UnicodeString& offsetHM, UnicodeString& result, UErrorCode& status);
808 
819  static UBool toCodePoints(const UnicodeString& str, UChar32* codeArray, int32_t capacity);
820 
831  UnicodeString& formatOffsetISO8601(int32_t offset, UBool isBasic, UBool useUtcIndicator,
832  UBool isShort, UBool ignoreSeconds, UnicodeString& result, UErrorCode& status) const;
833 
841  UnicodeString& formatOffsetLocalizedGMT(int32_t offset, UBool isShort, UnicodeString& result, UErrorCode& status) const;
842 
857  int32_t parseOffsetISO8601(const UnicodeString& text, ParsePosition& pos, UBool extendedOnly,
858  UBool* hasDigitOffset = NULL) const;
859 
867  void appendOffsetDigits(UnicodeString& buf, int32_t n, uint8_t minDigits) const;
868 
881  int32_t parseOffsetLocalizedGMT(const UnicodeString& text, ParsePosition& pos,
882  UBool isShort, UBool* hasDigitOffset) const;
883 
893  int32_t parseOffsetLocalizedGMTPattern(const UnicodeString& text, int32_t start,
894  UBool isShort, int32_t& parsedLen) const;
895 
904  int32_t parseOffsetFields(const UnicodeString& text, int32_t start, UBool isShort, int32_t& parsedLen) const;
905 
917  int32_t parseOffsetFieldsWithPattern(const UnicodeString& text, int32_t start,
918  UVector* patternItems, UBool forceSingleHourDigit, int32_t& hour, int32_t& min, int32_t& sec) const;
919 
927  int32_t parseAbuttingOffsetFields(const UnicodeString& text, int32_t start, int32_t& parsedLen) const;
928 
936  int32_t parseOffsetDefaultLocalizedGMT(const UnicodeString& text, int start, int32_t& parsedLen) const;
937 
946  int32_t parseDefaultOffsetFields(const UnicodeString& text, int32_t start, UChar separator,
947  int32_t& parsedLen) const;
948 
963  int32_t parseOffsetFieldWithLocalizedDigits(const UnicodeString& text, int32_t start,
964  uint8_t minDigits, uint8_t maxDigits, uint16_t minVal, uint16_t maxVal, int32_t& parsedLen) const;
965 
975  int32_t parseSingleLocalizedDigit(const UnicodeString& text, int32_t start, int32_t& len) const;
976 
986  static UnicodeString& formatOffsetWithAsciiDigits(int32_t offset, UChar sep,
987  OffsetFields minFields, OffsetFields maxFields, UnicodeString& result);
988 
1001  static int32_t parseAbuttingAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos,
1002  OffsetFields minFields, OffsetFields maxFields, UBool fixedHourWidth);
1003 
1016  static int32_t parseAsciiOffsetFields(const UnicodeString& text, ParsePosition& pos, UChar sep,
1017  OffsetFields minFields, OffsetFields maxFields);
1018 
1025  static UnicodeString& unquote(const UnicodeString& pattern, UnicodeString& result);
1026 
1032  void initGMTOffsetPatterns(UErrorCode& status);
1033 
1040  void checkAbuttingHoursAndMinutes();
1041 
1047  TimeZone* createTimeZoneForOffset(int32_t offset) const;
1048 
1054  static UTimeZoneFormatTimeType getTimeType(UTimeZoneNameType nameType);
1055 
1064  UnicodeString& getTimeZoneID(const TimeZoneNames::MatchInfoCollection* matches, int32_t idx, UnicodeString& tzID) const;
1065 
1066 
1074  UnicodeString& parseZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1075 
1083  UnicodeString& parseShortZoneID(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1084 
1092  UnicodeString& parseExemplarLocation(const UnicodeString& text, ParsePosition& pos, UnicodeString& tzID) const;
1093 };
1094 
1096 
1097 #endif /* !UCONFIG_NO_FORMATTING */
1098 #endif
When a time zone display name is not found within a set of display names used for the specified style...
Definition: tzfmt.h:236
Base class for all formats.
Definition: format.h:94
UTimeZoneFormatGMTOffsetPatternType
Constants for GMT offset pattern types.
Definition: tzfmt.h:157
Negative offset with hours and minutes fields.
Definition: tzfmt.h:172
TimeZoneFormat supports time zone display name formatting and parsing.
Definition: tzfmt.h:273
Fixed width ISO 8601 local time difference (basic format) or the UTC indicator.
Definition: tzfmt.h:86
ISO 8601 local time difference (basic format) with optional seconds field.
Definition: tzfmt.h:107
UTimeZoneFormatParseOption
Constants for parse option flags, used for specifying optional parse behavior.
Definition: tzfmt.h:224
Negative offset with hours field.
Definition: tzfmt.h:187
UTimeZoneFormatTimeType
Constants for time types used by TimeZoneFormat APIs for receiving time type (standard time...
Definition: tzfmt.h:202
Generic location format, such as "United States Time (New York)", "Italy Time".
Definition: tzfmt.h:34
ISO 8601 local time difference (extended format) with optional seconds field, or the UTC indicator...
Definition: tzfmt.h:128
virtual UClassID getDynamicClassID() const
ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
Short localized GMT offset format, such as "GMT-5", "UTC+1:30" This style is equivalent to the LDML d...
Definition: tzfmt.h:65
Positive offset with hours field.
Definition: tzfmt.h:182
C++ API: TimeZone object.
double UDate
Date and Time data type.
Definition: utypes.h:201
#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:256
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:91
Negative offset with hours, minutes and seconds fields.
Definition: tzfmt.h:177
virtual Format * clone() const =0
Clone this object polymorphically.
TimeZone represents a time zone offset, and also figures out daylight savings.
Definition: timezone.h:129
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:82
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside...
Definition: utypes.h:358
Fixed width ISO 8601 local time difference (basic format).
Definition: tzfmt.h:93
Exemplar location, such as "Los Angeles" and "Paris".
Definition: tzfmt.h:150
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:129
MatchInfoCollection represents a collection of time zone name matches used by TimeZoneNames#find.
Definition: tznames.h:298
Fixed width ISO 8601 local time difference (extended format) or the UTC indicator.
Definition: tzfmt.h:114
Daylight saving time.
Definition: tzfmt.h:217
Positive offset with hours and minutes fields.
Definition: tzfmt.h:162
TimeZoneNames is an abstract class representing the time zone display name data model defined by UTS#...
Definition: tznames.h:127
Short ISO 8601 locale time difference (basic format).
Definition: tzfmt.h:79
C++ API: TimeZoneNames.
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:332
#define NULL
Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.
Definition: utypes.h:186
ISO 8601 local time difference (basic format) with optional seconds field, or the UTC indicator...
Definition: tzfmt.h:100
UnicodeString & format(const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
Formats an object to produce a string.
UTimeZoneFormatStyle
Constants for time zone display format style used by format/parse APIs in TimeZoneFormat.
Definition: tzfmt.h:29
Time Zone ID, such as "America/Los_Angeles".
Definition: tzfmt.h:140
Specific short format, such as "EST", "PDT".
Definition: tzfmt.h:54
uint16_t UChar
Define UChar to be UCHAR_TYPE, if that is #defined (for example, to char16_t), or wchar_t if that is ...
Definition: umachine.h:312
#define U_CDECL_END
This is used to end a declaration of a library private ICU C API.
Definition: umachine.h:83
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:130
Positive offset with hours, minutes and seconds fields.
Definition: tzfmt.h:167
Short Time Zone ID (BCP 47 Unicode location extension, time zone type value), such as "uslax"...
Definition: tzfmt.h:145
Generic long non-location format, such as "Eastern Time".
Definition: tzfmt.h:39
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:476
FieldPosition is a simple class used by Format and its subclasses to identify fields in formatted out...
Definition: fieldpos.h:106
ParsePosition is a simple class used by Format and its subclasses to keep track of the current positi...
Definition: parsepos.h:47
virtual UBool operator==(const Format &other) const =0
Return true if the given Format objects are semantically equal.
Standard time.
Definition: tzfmt.h:212
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:121
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:245
Specific long format, such as "Eastern Standard Time".
Definition: tzfmt.h:49
Formattable objects can be passed to the Format class or its subclasses for formatting.
Definition: fmtable.h:66
UTimeZoneNameType
Constants for time zone display name types.
Definition: tznames.h:27
Short ISO 8601 local time difference (basic format) or the UTC indicator.
Definition: tzfmt.h:72
ISO 8601 local time difference (extended format) with optional seconds field.
Definition: tzfmt.h:135
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:59
Number of UTimeZoneFormatGMTOffsetPatternType types.
Definition: tzfmt.h:194
Generic short non-location format, such as "ET".
Definition: tzfmt.h:44
int8_t UBool
The ICU boolean type.
Definition: umachine.h:234
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:185