ICU 65.1  65.1
Public Member Functions | Static Public Member Functions | Protected Member Functions
icu::TimeZoneFormat Class Reference

TimeZoneFormat supports time zone display name formatting and parsing. More...

#include <tzfmt.h>

Inheritance diagram for icu::TimeZoneFormat:
icu::Format icu::UObject icu::UMemory

Public Member Functions

 TimeZoneFormat (const TimeZoneFormat &other)
 Copy constructor. More...
 
virtual ~TimeZoneFormat ()
 Destructor. More...
 
TimeZoneFormatoperator= (const TimeZoneFormat &other)
 Assignment operator. More...
 
virtual UBool operator== (const Format &other) const
 Return true if the given Format objects are semantically equal. More...
 
virtual TimeZoneFormatclone () const
 Clone this object polymorphically. More...
 
const TimeZoneNamesgetTimeZoneNames () const
 Returns the time zone display name data used by this instance. More...
 
void adoptTimeZoneNames (TimeZoneNames *tznames)
 Sets the time zone display name data to this format instnace. More...
 
void setTimeZoneNames (const TimeZoneNames &tznames)
 Sets the time zone display name data to this format instnace. More...
 
UnicodeStringgetGMTPattern (UnicodeString &pattern) const
 Returns the localized GMT format pattern. More...
 
void setGMTPattern (const UnicodeString &pattern, UErrorCode &status)
 Sets the localized GMT format pattern. More...
 
UnicodeStringgetGMTOffsetPattern (UTimeZoneFormatGMTOffsetPatternType type, UnicodeString &pattern) const
 Returns the offset pattern used for localized GMT format. More...
 
void setGMTOffsetPattern (UTimeZoneFormatGMTOffsetPatternType type, const UnicodeString &pattern, UErrorCode &status)
 Sets the offset pattern for the given offset type. More...
 
UnicodeStringgetGMTOffsetDigits (UnicodeString &digits) const
 Returns the decimal digit characters used for localized GMT format. More...
 
void setGMTOffsetDigits (const UnicodeString &digits, UErrorCode &status)
 Sets the decimal digit characters used for localized GMT format. More...
 
UnicodeStringgetGMTZeroFormat (UnicodeString &gmtZeroFormat) const
 Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0). More...
 
void setGMTZeroFormat (const UnicodeString &gmtZeroFormat, UErrorCode &status)
 Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0). More...
 
uint32_t getDefaultParseOptions (void) const
 Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse options used by this object. More...
 
void setDefaultParseOptions (uint32_t flags)
 Sets the default parse options. More...
 
UnicodeStringformatOffsetISO8601Basic (int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds, UnicodeString &result, UErrorCode &status) const
 Returns the ISO 8601 basic time zone string for the given offset. More...
 
UnicodeStringformatOffsetISO8601Extended (int32_t offset, UBool useUtcIndicator, UBool isShort, UBool ignoreSeconds, UnicodeString &result, UErrorCode &status) const
 Returns the ISO 8601 extended time zone string for the given offset. More...
 
UnicodeStringformatOffsetLocalizedGMT (int32_t offset, UnicodeString &result, UErrorCode &status) const
 Returns the localized GMT(UTC) offset format for the given offset. More...
 
UnicodeStringformatOffsetShortLocalizedGMT (int32_t offset, UnicodeString &result, UErrorCode &status) const
 Returns the short localized GMT(UTC) offset format for the given offset. More...
 
virtual UnicodeStringformat (UTimeZoneFormatStyle style, const TimeZone &tz, UDate date, UnicodeString &name, UTimeZoneFormatTimeType *timeType=NULL) const
 Returns the display name of the time zone at the given date for the style. More...
 
int32_t parseOffsetISO8601 (const UnicodeString &text, ParsePosition &pos) const
 Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string. More...
 
int32_t parseOffsetLocalizedGMT (const UnicodeString &text, ParsePosition &pos) const
 Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string. More...
 
int32_t parseOffsetShortLocalizedGMT (const UnicodeString &text, ParsePosition &pos) const
 Returns offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string. More...
 
virtual TimeZoneparse (UTimeZoneFormatStyle style, const UnicodeString &text, ParsePosition &pos, int32_t parseOptions, UTimeZoneFormatTimeType *timeType=NULL) const
 Returns a TimeZone by parsing the time zone string according to the given parse position, the specified format style and parse options. More...
 
TimeZoneparse (UTimeZoneFormatStyle style, const UnicodeString &text, ParsePosition &pos, UTimeZoneFormatTimeType *timeType=NULL) const
 Returns a TimeZone by parsing the time zone string according to the given parse position, the specified format style and the default parse options. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format an object to produce a time zone display string using localized GMT offset format. More...
 
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const
 Parse a string to produce an object. More...
 
virtual UClassID getDynamicClassID () const
 ICU "poor man's RTTI", returns a UClassID for the actual class. More...
 
- Public Member Functions inherited from icu::Format
virtual ~Format ()
 Destructor. More...
 
UBool operator!= (const Format &other) const
 Return true if the given Format objects are not semantically equal. More...
 
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
 Formats an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an object to produce a string. More...
 
void parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
 Parses a string to produce an object. More...
 
Locale getLocale (ULocDataLocaleType type, UErrorCode &status) const
 Get the locale for this format object. More...
 
const char * getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
 Get the locale for this format object. More...
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 

Static Public Member Functions

static TimeZoneFormatcreateInstance (const Locale &locale, UErrorCode &status)
 Creates an instance of TimeZoneFormat for the given locale. More...
 
static UClassID getStaticClassID (void)
 ICU "poor man's RTTI", returns a UClassID for this class. More...
 

Protected Member Functions

 TimeZoneFormat (const Locale &locale, UErrorCode &status)
 Constructs a TimeZoneFormat object for the specified locale. More...
 
- Protected Member Functions inherited from icu::Format
void setLocaleIDs (const char *valid, const char *actual)
 
 Format ()
 Default constructor for subclass use only. More...
 
 Format (const Format &)
 
Formatoperator= (const Format &)
 

Additional Inherited Members

- Static Protected Member Functions inherited from icu::Format
static void syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
 Simple function for initializing a UParseError from a UnicodeString. More...
 

Detailed Description

TimeZoneFormat supports time zone display name formatting and parsing.

An instance of TimeZoneFormat works as a subformatter of SimpleDateFormat, but you can also directly get a new instance of TimeZoneFormat and formatting/parsing time zone display names.

ICU implements the time zone display names defined by UTS#35 Unicode Locale Data Markup Language (LDML). TimeZoneNames represents the time zone display name data model and this class implements the algorithm for actual formatting and parsing.

See also
SimpleDateFormat
TimeZoneNames
Stable:
ICU 50

Definition at line 274 of file tzfmt.h.

Constructor & Destructor Documentation

◆ TimeZoneFormat() [1/2]

icu::TimeZoneFormat::TimeZoneFormat ( const TimeZoneFormat other)

Copy constructor.

Stable:
ICU 50

◆ ~TimeZoneFormat()

virtual icu::TimeZoneFormat::~TimeZoneFormat ( )
virtual

Destructor.

Stable:
ICU 50

◆ TimeZoneFormat() [2/2]

icu::TimeZoneFormat::TimeZoneFormat ( const Locale locale,
UErrorCode status 
)
protected

Constructs a TimeZoneFormat object for the specified locale.

Parameters
localethe locale
statusreceives the status.
Stable:
ICU 50

Member Function Documentation

◆ adoptTimeZoneNames()

void icu::TimeZoneFormat::adoptTimeZoneNames ( TimeZoneNames tznames)

Sets the time zone display name data to this format instnace.

The caller should not delete the TimeZoenNames object after it is adopted by this call.

Parameters
tznamesTimeZoneNames object to be adopted.
Stable:
ICU 50

◆ clone()

virtual TimeZoneFormat* icu::TimeZoneFormat::clone ( ) const
virtual

Clone this object polymorphically.

The caller is responsible for deleting the result when done.

Returns
A copy of the object
Stable:
ICU 50

Implements icu::Format.

◆ createInstance()

static TimeZoneFormat* icu::TimeZoneFormat::createInstance ( const Locale locale,
UErrorCode status 
)
static

Creates an instance of TimeZoneFormat for the given locale.

Parameters
localeThe locale.
statusReceives the status.
Returns
An instance of TimeZoneFormat for the given locale, owned by the caller.
Stable:
ICU 50

◆ format() [1/2]

virtual UnicodeString& icu::TimeZoneFormat::format ( UTimeZoneFormatStyle  style,
const TimeZone tz,
UDate  date,
UnicodeString name,
UTimeZoneFormatTimeType timeType = NULL 
) const
virtual

Returns the display name of the time zone at the given date for the style.

Parameters
styleThe style (e.g. UTZFMT_STYLE_GENERIC_LONG, UTZFMT_STYLE_LOCALIZED_GMT...)
tzThe time zone.
dateThe date.
nameReceives the display name.
timeTypethe output argument for receiving the time type (standard/daylight/unknown) used for the display name, or NULL if the information is not necessary.
Returns
A reference to the result
See also
UTimeZoneFormatStyle
UTimeZoneFormatTimeType
Stable:
ICU 50

◆ format() [2/2]

virtual UnicodeString& icu::TimeZoneFormat::format ( const Formattable obj,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const
virtual

Format an object to produce a time zone display string using localized GMT offset format.

This method handles Formattable objects with a TimeZone. If a the Formattable object type is not a TimeZone, then it returns a failing UErrorCode.

Parameters
objThe object to format. Must be a TimeZone.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 50

Implements icu::Format.

◆ formatOffsetISO8601Basic()

UnicodeString& icu::TimeZoneFormat::formatOffsetISO8601Basic ( int32_t  offset,
UBool  useUtcIndicator,
UBool  isShort,
UBool  ignoreSeconds,
UnicodeString result,
UErrorCode status 
) const

Returns the ISO 8601 basic time zone string for the given offset.

For example, "-08", "-0830" and "Z"

Parameters
offsetthe offset from GMT(UTC) in milliseconds.
useUtcIndicatortrue if ISO 8601 UTC indicator "Z" is used when the offset is 0.
isShorttrue if shortest form is used.
ignoreSecondstrue if non-zero offset seconds is appended.
resultReceives the ISO format string.
statusReceives the status
Returns
the ISO 8601 basic format.
See also
formatOffsetISO8601Extended
parseOffsetISO8601
Stable:
ICU 51

◆ formatOffsetISO8601Extended()

UnicodeString& icu::TimeZoneFormat::formatOffsetISO8601Extended ( int32_t  offset,
UBool  useUtcIndicator,
UBool  isShort,
UBool  ignoreSeconds,
UnicodeString result,
UErrorCode status 
) const

Returns the ISO 8601 extended time zone string for the given offset.

For example, "-08:00", "-08:30" and "Z"

Parameters
offsetthe offset from GMT(UTC) in milliseconds.
useUtcIndicatortrue if ISO 8601 UTC indicator "Z" is used when the offset is 0.
isShorttrue if shortest form is used.
ignoreSecondstrue if non-zero offset seconds is appended.
resultReceives the ISO format string.
statusReceives the status
Returns
the ISO 8601 basic format.
See also
formatOffsetISO8601Extended
parseOffsetISO8601
Stable:
ICU 51

◆ formatOffsetLocalizedGMT()

UnicodeString& icu::TimeZoneFormat::formatOffsetLocalizedGMT ( int32_t  offset,
UnicodeString result,
UErrorCode status 
) const

Returns the localized GMT(UTC) offset format for the given offset.

The localized GMT offset is defined by;

This format always uses 2 digit hours and minutes. When the given offset has non-zero seconds, 2 digit seconds field will be appended. For example, GMT+05:00 and GMT+05:28:06.

Parameters
offsetthe offset from GMT(UTC) in milliseconds.
statusReceives the status
resultReceives the localized GMT format string.
Returns
A reference to the result.
See also
parseOffsetLocalizedGMT
Stable:
ICU 50

◆ formatOffsetShortLocalizedGMT()

UnicodeString& icu::TimeZoneFormat::formatOffsetShortLocalizedGMT ( int32_t  offset,
UnicodeString result,
UErrorCode status 
) const

Returns the short localized GMT(UTC) offset format for the given offset.

The short localized GMT offset is defined by;

This format uses the shortest representation of offset. The hours field does not have leading zero and lower fields with zero will be truncated. For example, GMT+5 and GMT+530.

Parameters
offsetthe offset from GMT(UTC) in milliseconds.
statusReceives the status
resultReceives the short localized GMT format string.
Returns
A reference to the result.
See also
parseOffsetShortLocalizedGMT
Stable:
ICU 51

◆ getDefaultParseOptions()

uint32_t icu::TimeZoneFormat::getDefaultParseOptions ( void  ) const

Returns the bitwise flags of UTimeZoneFormatParseOption representing the default parse options used by this object.

Returns
the default parse options.
See also
ParseOption
Stable:
ICU 50

◆ getDynamicClassID()

virtual UClassID icu::TimeZoneFormat::getDynamicClassID ( ) const
virtual

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
ICU 50

Reimplemented from icu::UObject.

◆ getGMTOffsetDigits()

UnicodeString& icu::TimeZoneFormat::getGMTOffsetDigits ( UnicodeString digits) const

Returns the decimal digit characters used for localized GMT format.

The return string contains exactly 10 code points (may include Unicode supplementary character) representing digit 0 to digit 9 in the ascending order.

Parameters
digitsReceives the decimal digits used for localized GMT format.
See also
setGMTOffsetDigits
Stable:
ICU 50

◆ getGMTOffsetPattern()

UnicodeString& icu::TimeZoneFormat::getGMTOffsetPattern ( UTimeZoneFormatGMTOffsetPatternType  type,
UnicodeString pattern 
) const

Returns the offset pattern used for localized GMT format.

Parameters
typeThe offset pattern type enum.
patternReceives the offset pattern.
Returns
A reference to the result pattern.
See also
setGMTOffsetPattern
Stable:
ICU 50

◆ getGMTPattern()

UnicodeString& icu::TimeZoneFormat::getGMTPattern ( UnicodeString pattern) const

Returns the localized GMT format pattern.

Parameters
patternReceives the localized GMT format pattern.
Returns
A reference to the result pattern.
See also
setGMTPattern
Stable:
ICU 50

◆ getGMTZeroFormat()

UnicodeString& icu::TimeZoneFormat::getGMTZeroFormat ( UnicodeString gmtZeroFormat) const

Returns the localized GMT format string for GMT(UTC) itself (GMT offset is 0).

Parameters
gmtZeroFormatReceives the localized GMT string string for GMT(UTC) itself.
Returns
A reference to the result GMT string.
See also
setGMTZeroFormat
Stable:
ICU 50

◆ getStaticClassID()

static UClassID icu::TimeZoneFormat::getStaticClassID ( void  )
static

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
ICU 50

◆ getTimeZoneNames()

const TimeZoneNames* icu::TimeZoneFormat::getTimeZoneNames ( ) const

Returns the time zone display name data used by this instance.

Returns
The time zone display name data.
Stable:
ICU 50

◆ operator=()

TimeZoneFormat& icu::TimeZoneFormat::operator= ( const TimeZoneFormat other)

Assignment operator.

Stable:
ICU 50

◆ operator==()

virtual UBool icu::TimeZoneFormat::operator== ( const Format other) const
virtual

Return true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters
otherThe object to be compared with.
Returns
Return TRUE if the given Format objects are semantically equal. Objects of different subclasses are considered unequal.
Stable:
ICU 50

Implements icu::Format.

◆ parse() [1/2]

virtual TimeZone* icu::TimeZoneFormat::parse ( UTimeZoneFormatStyle  style,
const UnicodeString text,
ParsePosition pos,
int32_t  parseOptions,
UTimeZoneFormatTimeType timeType = NULL 
) const
virtual

Returns a TimeZone by parsing the time zone string according to the given parse position, the specified format style and parse options.

Parameters
textThe text contains a time zone string at the position.
styleThe format style
posThe position.
parseOptionsThe parse options repesented by bitwise flags of UTimeZoneFormatParseOption.
timeTypeThe output argument for receiving the time type (standard/daylight/unknown), or NULL if the information is not necessary.
Returns
A TimeZone, or null if the input could not be parsed.
See also
UTimeZoneFormatStyle
UTimeZoneFormatParseOption
UTimeZoneFormatTimeType
Stable:
ICU 50

◆ parse() [2/2]

TimeZone* icu::TimeZoneFormat::parse ( UTimeZoneFormatStyle  style,
const UnicodeString text,
ParsePosition pos,
UTimeZoneFormatTimeType timeType = NULL 
) const

Returns a TimeZone by parsing the time zone string according to the given parse position, the specified format style and the default parse options.

Parameters
textThe text contains a time zone string at the position.
styleThe format style
posThe position.
timeTypeThe output argument for receiving the time type (standard/daylight/unknown), or NULL if the information is not necessary.
Returns
A TimeZone, or null if the input could not be parsed.
See also
UTimeZoneFormatStyle
UTimeZoneFormatParseOption
UTimeZoneFormatTimeType
Stable:
ICU 50

◆ parseObject()

virtual void icu::TimeZoneFormat::parseObject ( const UnicodeString source,
Formattable result,
ParsePosition parse_pos 
) const
virtual

Parse a string to produce an object.

This methods handles parsing of time zone display strings into Formattable objects with TimeZone.

Parameters
sourceThe string to be parsed into an object.
resultFormattable to be set to the parse result. If parse fails, return contents are undefined.
parse_posThe position to start parsing at. Upon return this param is set to the position after the last character successfully parsed. If the source is not parsed successfully, this param will remain unchanged.
Returns
A newly created Formattable* object, or NULL on failure. The caller owns this and should delete it when done.
Stable:
ICU 50

Implements icu::Format.

◆ parseOffsetISO8601()

int32_t icu::TimeZoneFormat::parseOffsetISO8601 ( const UnicodeString text,
ParsePosition pos 
) const

Returns offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string.

When the given string is not an ISO 8601 time zone string, this method sets the current position as the error index to ParsePosition pos and returns 0.

Parameters
textThe text contains ISO8601 style time zone string (e.g. "-08:00", "Z") at the position.
posThe ParsePosition object.
Returns
The offset from GMT(UTC) in milliseconds for the given ISO 8601 style time zone string.
See also
formatOffsetISO8601Basic
formatOffsetISO8601Extended
Stable:
ICU 50

◆ parseOffsetLocalizedGMT()

int32_t icu::TimeZoneFormat::parseOffsetLocalizedGMT ( const UnicodeString text,
ParsePosition pos 
) const

Returns offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.

When the given string cannot be parsed, this method sets the current position as the error index to ParsePosition pos and returns 0.

Parameters
textThe text contains a localized GMT offset string at the position.
posThe ParsePosition object.
Returns
The offset from GMT(UTC) in milliseconds for the given localized GMT offset format string.
See also
formatOffsetLocalizedGMT
Stable:
ICU 50

◆ parseOffsetShortLocalizedGMT()

int32_t icu::TimeZoneFormat::parseOffsetShortLocalizedGMT ( const UnicodeString text,
ParsePosition pos 
) const

Returns offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.

When the given string cannot be parsed, this method sets the current position as the error index to ParsePosition pos and returns 0.

Parameters
textThe text contains a short localized GMT offset string at the position.
posThe ParsePosition object.
Returns
The offset from GMT(UTC) in milliseconds for the given short localized GMT offset format string.
See also
formatOffsetShortLocalizedGMT
Stable:
ICU 51

◆ setDefaultParseOptions()

void icu::TimeZoneFormat::setDefaultParseOptions ( uint32_t  flags)

Sets the default parse options.

Note: By default, an instance of TimeZoneFormat created by createInstance has no parse options set (UTZFMT_PARSE_OPTION_NONE). To specify multipe options, use bitwise flags of UTimeZoneFormatParseOption.

See also
UTimeZoneFormatParseOption
Stable:
ICU 50

◆ setGMTOffsetDigits()

void icu::TimeZoneFormat::setGMTOffsetDigits ( const UnicodeString digits,
UErrorCode status 
)

Sets the decimal digit characters used for localized GMT format.

The input digits must contain exactly 10 code points (Unicode supplementary characters are also allowed) representing digit 0 to digit 9 in the ascending order. When the input digits does not satisfy the condition, U_ILLEGAL_ARGUMENT_ERROR will be set to the return status.

Parameters
digitsThe decimal digits used for localized GMT format.
statusReceives the status.
See also
getGMTOffsetDigits
Stable:
ICU 50

◆ setGMTOffsetPattern()

void icu::TimeZoneFormat::setGMTOffsetPattern ( UTimeZoneFormatGMTOffsetPatternType  type,
const UnicodeString pattern,
UErrorCode status 
)

Sets the offset pattern for the given offset type.

Parameters
typeThe offset pattern type enum.
patternThe offset pattern used for localized GMT format for the type.
statusReceives the status.
See also
getGMTOffsetPattern
Stable:
ICU 50

◆ setGMTPattern()

void icu::TimeZoneFormat::setGMTPattern ( const UnicodeString pattern,
UErrorCode status 
)

Sets the localized GMT format pattern.

The pattern must contain a single argument {0}, for example "GMT {0}".

Parameters
patternThe localized GMT format pattern to be used by this object.
statusRecieves the status.
See also
getGMTPattern
Stable:
ICU 50

◆ setGMTZeroFormat()

void icu::TimeZoneFormat::setGMTZeroFormat ( const UnicodeString gmtZeroFormat,
UErrorCode status 
)

Sets the localized GMT format string for GMT(UTC) itself (GMT offset is 0).

Parameters
gmtZeroFormatThe localized GMT format string for GMT(UTC).
statusReceives the status.
See also
getGMTZeroFormat
Stable:
ICU 50

◆ setTimeZoneNames()

void icu::TimeZoneFormat::setTimeZoneNames ( const TimeZoneNames tznames)

Sets the time zone display name data to this format instnace.

Parameters
tznamesTimeZoneNames object to be set.
Stable:
ICU 50

The documentation for this class was generated from the following file: