TimeZoneNames is an abstract class representing the time zone display name data model defined
* by UTS#35 Unicode Locale Data Markup Language (LDML).
* The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
* by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
* * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time". * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make * much sense for most of people. *
* In CLDR (which uses LDML for representing locale data), the display name * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern". * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern". *
* Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox" * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone * to meta zones mapping data are stored by date range. * *
Note: * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU * canonical time zone IDs. * *
* In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may * have a specific name that is not shared with other time zones. * * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only * used for "Europe/London". * *
* {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone. * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName}, * or both. * *
* The default TimeZoneNames implementation returned by {@link #createInstance}
* uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
* IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
* {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
* what locale is used for getting an instance of TimeZoneNames.
*
* @stable ICU 50
*/
class U_I18N_API TimeZoneNames : public UObject {
public:
/**
* Destructor.
* @stable ICU 50
*/
virtual ~TimeZoneNames();
/**
* Return true if the given TimeZoneNames objects are semantically equal.
* @param other the object to be compared with.
* @return Return TRUE if the given Format objects are semantically equal.
* @stable ICU 50
*/
virtual UBool operator==(const TimeZoneNames& other) const = 0;
/**
* Return true if the given TimeZoneNames objects are not semantically
* equal.
* @param other the object to be compared with.
* @return Return TRUE if the given Format objects are not semantically equal.
* @stable ICU 50
*/
UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); }
/**
* Clone this object polymorphically. The caller is responsible
* for deleting the result when done.
* @return A copy of the object
* @stable ICU 50
*/
virtual TimeZoneNames* clone() const = 0;
/**
* Returns an instance of TimeZoneNames for the specified locale.
*
* @param locale The locale.
* @param status Receives the status.
* @return An instance of TimeZoneNames
* @stable ICU 50
*/
static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
/**
* Returns an instance of TimeZoneNames containing only short specific
* zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
* compatible with the IANA tz database's zone abbreviations (not localized).
*
* Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed
* as Israel Standard Time for Israel, while it is parsed as India Standard Time for
* all other regions). The zone names returned by this instance are not localized.
* @stable ICU 54
*/
static TimeZoneNames* U_EXPORT2 createTZDBInstance(const Locale& locale, UErrorCode& status);
/**
* Returns an enumeration of all available meta zone IDs.
* @param status Receives the status.
* @return an enumeration object, owned by the caller.
* @stable ICU 50
*/
virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
/**
* Returns an enumeration of all available meta zone IDs used by the given time zone.
* @param tzID The canoical tiem zone ID.
* @param status Receives the status.
* @return an enumeration object, owned by the caller.
* @stable ICU 50
*/
virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
/**
* Returns the meta zone ID for the given canonical time zone ID at the given date.
* @param tzID The canonical time zone ID.
* @param date The date.
* @param mzID Receives the meta zone ID for the given time zone ID at the given date. If the time zone does not have a
* corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
* is set.
* @return A reference to the result.
* @stable ICU 50
*/
virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
/**
* Returns the reference zone ID for the given meta zone ID for the region.
*
* Note: Each meta zone must have a reference zone associated with a special region "001" (world).
* Some meta zones may have region specific reference zone IDs other than the special region
* "001". When a meta zone does not have any region specific reference zone IDs, this method
* return the reference zone ID for the special region "001" (world).
*
* @param mzID The meta zone ID.
* @param region The region.
* @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
* region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
* is set.
* @return A reference to the result.
* @stable ICU 50
*/
virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
/**
* Returns the display name of the meta zone.
* @param mzID The meta zone ID.
* @param type The display name type. See {@link #UTimeZoneNameType}.
* @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
* meta zone with the specified type or the implementation does not provide any display names associated
* with meta zones, "bogus" state is set.
* @return A reference to the result.
* @stable ICU 50
*/
virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
/**
* Returns the display name of the time zone. Unlike {@link #getDisplayName},
* this method does not get a name from a meta zone used by the time zone.
* @param tzID The canonical time zone ID.
* @param type The display name type. See {@link #UTimeZoneNameType}.
* @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
* time zone with the specified type, "bogus" state is set.
* @return A reference to the result.
* @stable ICU 50
*/
virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
/**
* Returns the exemplar location name for the given time zone. When this object does not have a localized location
* name, the default implementation may still returns a programmatically generated name with the logic described
* below.
*
* Note: This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
* result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
* time zone, then calls {@link #getMetaZoneDisplayName}.
*
* @param tzID The canonical time zone ID.
* @param type The display name type. See {@link #UTimeZoneNameType}.
* @param date The date.
* @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
* name for the time zone with the specified type and date, "bogus" state is set.
* @return A reference to the result.
* @stable ICU 50
*/
virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
/**
* @internal ICU internal only, for specific users only until proposed publicly.
*/
virtual void loadAllDisplayNames(UErrorCode& status);
/**
* @internal ICU internal only, for specific users only until proposed publicly.
*/
virtual void getDisplayNames(const UnicodeString& tzID, const UTimeZoneNameType types[], int32_t numTypes, UDate date, UnicodeString dest[], UErrorCode& status) const;
/**
* MatchInfoCollection represents a collection of time zone name matches used by
* {@link TimeZoneNames#find}.
* @internal
*/
class U_I18N_API MatchInfoCollection : public UMemory {
public:
/**
* Constructor.
* @internal
*/
MatchInfoCollection();
/**
* Destructor.
* @internal
*/
virtual ~MatchInfoCollection();
#ifndef U_HIDE_INTERNAL_API
/**
* Adds a zone match.
* @param nameType The name type.
* @param matchLength The match length.
* @param tzID The time zone ID.
* @param status Receives the status
* @internal
*/
void addZone(UTimeZoneNameType nameType, int32_t matchLength,
const UnicodeString& tzID, UErrorCode& status);
/**
* Adds a meata zone match.
* @param nameType The name type.
* @param matchLength The match length.
* @param mzID The metazone ID.
* @param status Receives the status
* @internal
*/
void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,
const UnicodeString& mzID, UErrorCode& status);
/**
* Returns the number of entries available in this object.
* @return The number of entries.
* @internal
*/
int32_t size() const;
/**
* Returns the time zone name type of a match at the specified index.
* @param idx The index
* @return The time zone name type. If the specified idx is out of range,
* it returns UTZNM_UNKNOWN.
* @see UTimeZoneNameType
* @internal
*/
UTimeZoneNameType getNameTypeAt(int32_t idx) const;
/**
* Returns the match length of a match at the specified index.
* @param idx The index
* @return The match length. If the specified idx is out of range,
* it returns 0.
* @internal
*/
int32_t getMatchLengthAt(int32_t idx) const;
/**
* Gets the zone ID of a match at the specified index.
* @param idx The index
* @param tzID Receives the zone ID.
* @return TRUE if the zone ID was set to tzID.
* @internal
*/
UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;
/**
* Gets the metazone ID of a match at the specified index.
* @param idx The index
* @param mzID Receives the metazone ID
* @return TRUE if the meta zone ID was set to mzID.
* @internal
*/
UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
#endif /* U_HIDE_INTERNAL_API */
private:
UVector* fMatches; // vector of MatchEntry
UVector* matches(UErrorCode& status);
};
/**
* Finds time zone name prefix matches for the input text at the
* given offset and returns a collection of the matches.
* @param text The text.
* @param start The starting offset within the text.
* @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
* or UTZNM_UNKNOWN for all name types.
* @param status Receives the status.
* @return A collection of matches (owned by the caller), or NULL if no matches are found.
* @see UTimeZoneNameType
* @see MatchInfoCollection
* @internal
*/
virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
};
U_NAMESPACE_END
#endif
#endif /* U_SHOW_CPLUSPLUS_API */
#endif