icuSources/i18n/unicode/dtfmtsym.h

   1 /*
   2 ********************************************************************************
   3 *   Copyright (C) 1997-2004, International Business Machines
   4 *   Corporation and others.  All Rights Reserved.
   5 ********************************************************************************
   6 *
   7 * File DTFMTSYM.H
   8 *
   9 * Modification History:
  10 *
  11 *   Date        Name        Description
  12 *   02/19/97    aliu        Converted from java.
  13 *    07/21/98    stephen        Added getZoneIndex()
  14 *                            Changed to match C++ conventions
  15 ********************************************************************************
  16 */
  17
  18 #ifndef DTFMTSYM_H
  19 #define DTFMTSYM_H
  20
  21 #include "unicode/utypes.h"
  22
  23 #if !UCONFIG_NO_FORMATTING
  24
  25 #include "unicode/uobject.h"
  26 #include "unicode/locid.h"
  27 #include "unicode/ures.h"
  28
  29 U_NAMESPACE_BEGIN
  30
  31 /* forward declaration */
  32 class SimpleDateFormat;
  33
  34 /**
  35  * DateFormatSymbols is a public class for encapsulating localizable date-time
  36  * formatting data -- including timezone data. DateFormatSymbols is used by
  37  * DateFormat and SimpleDateFormat.
  38  * <P>
  39  * Rather than first creating a DateFormatSymbols to get a date-time formatter
  40  * by using a SimpleDateFormat constructor, clients are encouraged to create a
  41  * date-time formatter using the getTimeInstance(), getDateInstance(), or
  42  * getDateTimeInstance() method in DateFormat. Each of these methods can return a
  43  * date/time formatter initialized with a default format pattern along with the
  44  * date-time formatting data for a given or default locale. After a formatter is
  45  * created, clients may modify the format pattern using the setPattern function
  46  * as so desired. For more information on using these formatter factory
  47  * functions, see DateFormat.
  48  * <P>
  49  * If clients decide to create a date-time formatter with a particular format
  50  * pattern and locale, they can do so with new SimpleDateFormat(aPattern,
  51  * new DateFormatSymbols(aLocale)).  This will load the appropriate date-time
  52  * formatting data from the locale.
  53  * <P>
  54  * DateFormatSymbols objects are clonable. When clients obtain a
  55  * DateFormatSymbols object, they can feel free to modify the date-time
  56  * formatting data as necessary. For instance, clients can
  57  * replace the localized date-time format pattern characters with the ones that
  58  * they feel easy to remember. Or they can change the representative cities
  59  * originally picked by default to using their favorite ones.
  60  * <P>
  61  * DateFormatSymbols are not expected to be subclassed. Data for a calendar is
  62  * loaded out of resource bundles.  The 'type' parameter indicates the type of
  63  * calendar, for example, "gregorian" or "japanese".  If the type is not gregorian
  64  * (or NULL, or an empty string) then the type is appended to the resource name,
  65  * for example,  'Eras_japanese' instead of 'Eras'.   If the resource 'Eras_japanese' did
  66  * not exist (even in root), then this class will fall back to just 'Eras', that is,
  67  * Gregorian data.  Therefore, the calendar implementor MUST ensure that the root
  68  * locale at least contains any resources that are to be particularized for the
  69  * calendar type.
  70  */
  71 class U_I18N_API DateFormatSymbols : public UObject {
  72 public:
  73     /**
  74      * Construct a DateFormatSymbols object by loading format data from
  75      * resources for the default locale, in the default calendar (Gregorian).
  76      * <P>
  77      * NOTE: This constructor will never fail; if it cannot get resource
  78      * data for the default locale, it will return a last-resort object
  79      * based on hard-coded strings.
  80      *
  81      * @param status    Status code.  Failure
  82      *                  results if the resources for the default cannot be
  83      *                  found or cannot be loaded
  84      * @stable ICU 2.0
  85      */
  86     DateFormatSymbols(UErrorCode& status);
  87
  88     /**
  89      * Construct a DateFormatSymbols object by loading format data from
  90      * resources for the given locale, in the default calendar (Gregorian).
  91      *
  92      * @param locale    Locale to load format data from.
  93      * @param status    Status code.  Failure
  94      *                  results if the resources for the locale cannot be
  95      *                  found or cannot be loaded
  96      * @stable ICU 2.0
  97      */
  98     DateFormatSymbols(const Locale& locale,
  99                       UErrorCode& status);
 100
 101     /**
 102      * Construct a DateFormatSymbols object by loading format data from
 103      * resources for the default locale, in the default calendar (Gregorian).
 104      * <P>
 105      * NOTE: This constructor will never fail; if it cannot get resource
 106      * data for the default locale, it will return a last-resort object
 107      * based on hard-coded strings.
 108      *
 109      * @param type      Type of calendar (as returned by Calendar::getType).
 110      *                  Will be used to access the correct set of strings.
 111      *                  (NULL or empty string defaults to "gregorian".)
 112      * @param status    Status code.  Failure
 113      *                  results if the resources for the default cannot be
 114      *                  found or cannot be loaded
 115      * @internal
 116      */
 117     DateFormatSymbols(const char *type, UErrorCode& status);
 118
 119     /**
 120      * Construct a DateFormatSymbols object by loading format data from
 121      * resources for the given locale, in the default calendar (Gregorian).
 122      *
 123      * @param locale    Locale to load format data from.
 124      * @param type      Type of calendar (as returned by Calendar::getType).
 125      *                  Will be used to access the correct set of strings.
 126      *                  (NULL or empty string defaults to "gregorian".)
 127      * @param status    Status code.  Failure
 128      *                  results if the resources for the locale cannot be
 129      *                  found or cannot be loaded
 130      * @internal
 131      */
 132     DateFormatSymbols(const Locale& locale,
 133                       const char *type,
 134                       UErrorCode& status);
 135
 136     /**
 137      * Copy constructor.
 138      * @stable ICU 2.0
 139      */
 140     DateFormatSymbols(const DateFormatSymbols&);
 141
 142     /**
 143      * Assignment operator.
 144      * @stable ICU 2.0
 145      */
 146     DateFormatSymbols& operator=(const DateFormatSymbols&);
 147
 148     /**
 149      * Destructor. This is nonvirtual because this class is not designed to be
 150      * subclassed.
 151      * @stable ICU 2.0
 152      */
 153     virtual ~DateFormatSymbols();
 154
 155     /**
 156      * Return true if another object is semantically equal to this one.
 157      *
 158      * @param other    the DateFormatSymbols object to be compared with.
 159      * @return         true if other is semantically equal to this.
 160      * @stable ICU 2.0
 161      */
 162     UBool operator==(const DateFormatSymbols& other) const;
 163
 164     /**
 165      * Return true if another object is semantically unequal to this one.
 166      *
 167      * @param other    the DateFormatSymbols object to be compared with.
 168      * @return         true if other is semantically unequal to this.
 169      * @stable ICU 2.0
 170      */
 171     UBool operator!=(const DateFormatSymbols& other) const { return !operator==(other); }
 172
 173     /**
 174      * Gets era strings. For example: "AD" and "BC".
 175      *
 176      * @param count    Filled in with length of the array.
 177      * @return         the era strings.
 178      * @stable ICU 2.0
 179      */
 180     const UnicodeString* getEras(int32_t& count) const;
 181
 182     /**
 183      * Sets era strings. For example: "AD" and "BC".
 184      * @param eras  Array of era strings (DateFormatSymbols retains ownership.)
 185      * @param count Filled in with length of the array.
 186      * @stable ICU 2.0
 187      */
 188     void setEras(const UnicodeString* eras, int32_t count);
 189
 190     /**
 191      * Gets month strings. For example: "January", "February", etc.
 192      * @param count Filled in with length of the array.
 193      * @return the month strings. (DateFormatSymbols retains ownership.)
 194      * @stable ICU 2.0
 195      */
 196     const UnicodeString* getMonths(int32_t& count) const;
 197
 198     /**
 199      * Sets month strings. For example: "January", "February", etc.
 200      *
 201      * @param months    the new month strings. (not adopted; caller retains ownership)
 202      * @param count     Filled in with length of the array.
 203      * @stable ICU 2.0
 204      */
 205     void setMonths(const UnicodeString* months, int32_t count);
 206
 207     /**
 208      * Gets short month strings. For example: "Jan", "Feb", etc.
 209      *
 210      * @param count Filled in with length of the array.
 211      * @return the short month strings. (DateFormatSymbols retains ownership.)
 212      * @stable ICU 2.0
 213      */
 214     const UnicodeString* getShortMonths(int32_t& count) const;
 215
 216     /**
 217      * Sets short month strings. For example: "Jan", "Feb", etc.
 218      * @param count        Filled in with length of the array.
 219      * @param shortMonths  the new short month strings. (not adopted; caller retains ownership)
 220      * @stable ICU 2.0
 221      */
 222     void setShortMonths(const UnicodeString* shortMonths, int32_t count);
 223
 224     /**
 225      * Gets weekday strings. For example: "Sunday", "Monday", etc.
 226      * @param count        Filled in with length of the array.
 227      * @return the weekday strings. (DateFormatSymbols retains ownership.)
 228      * @stable ICU 2.0
 229      */
 230     const UnicodeString* getWeekdays(int32_t& count) const;
 231
 232     /**
 233      * Sets weekday strings. For example: "Sunday", "Monday", etc.
 234      * @param weekdays     the new weekday strings. (not adopted; caller retains ownership)
 235      * @param count        Filled in with length of the array.
 236      * @stable ICU 2.0
 237      */
 238     void setWeekdays(const UnicodeString* weekdays, int32_t count);
 239
 240     /**
 241      * Gets short weekday strings. For example: "Sun", "Mon", etc.
 242      * @param count        Filled in with length of the array.
 243      * @return             the short weekday strings. (DateFormatSymbols retains ownership.)
 244      * @stable ICU 2.0
 245      */
 246     const UnicodeString* getShortWeekdays(int32_t& count) const;
 247
 248     /**
 249      * Sets short weekday strings. For example: "Sun", "Mon", etc.
 250      * @param shortWeekdays  the new short weekday strings. (not adopted; caller retains ownership)
 251      * @param count          Filled in with length of the array.
 252      * @stable ICU 2.0
 253      */
 254     void setShortWeekdays(const UnicodeString* shortWeekdays, int32_t count);
 255
 256     /**
 257      * Gets AM/PM strings. For example: "AM" and "PM".
 258      * @param count        Filled in with length of the array.
 259      * @return             the weekday strings. (DateFormatSymbols retains ownership.)
 260      * @stable ICU 2.0
 261      */
 262     const UnicodeString* getAmPmStrings(int32_t& count) const;
 263
 264     /**
 265      * Sets ampm strings. For example: "AM" and "PM".
 266      * @param ampms        the new ampm strings. (not adopted; caller retains ownership)
 267      * @param count        Filled in with length of the array.
 268      * @stable ICU 2.0
 269      */
 270     void setAmPmStrings(const UnicodeString* ampms, int32_t count);
 271
 272     /**
 273      * Gets timezone strings. These strings are stored in a 2-dimensional array.
 274      * @param rowCount      Output param to receive number of rows.
 275      * @param columnCount   Output param to receive number of columns.
 276      * @return              The timezone strings as a 2-d array. (DateFormatSymbols retains ownership.)
 277      * @stable ICU 2.0
 278      */
 279     const UnicodeString** getZoneStrings(int32_t& rowCount, int32_t& columnCount) const;
 280
 281     /**
 282      * Sets timezone strings. These strings are stored in a 2-dimensional array.
 283      * @param strings       The timezone strings as a 2-d array to be copied. (not adopted; caller retains ownership)
 284      * @param rowCount      The number of rows (count of first index).
 285      * @param columnCount   The number of columns (count of second index).
 286      * @stable ICU 2.0
 287      */
 288     void setZoneStrings(const UnicodeString* const* strings, int32_t rowCount, int32_t columnCount);
 289
 290     /**
 291      * Get the non-localized date-time pattern characters.
 292      * @return    the non-localized date-time pattern characters
 293      * @stable ICU 2.0
 294      */
 295     static const UChar * U_EXPORT2 getPatternUChars(void);
 296
 297     /**
 298      * Gets localized date-time pattern characters. For example: 'u', 't', etc.
 299      * @param result    Output param which will receive the localized date-time pattern characters.
 300      * @return          A reference to 'result'.
 301      * @stable ICU 2.0
 302      */
 303     UnicodeString& getLocalPatternChars(UnicodeString& result) const;
 304
 305     /**
 306      * Sets localized date-time pattern characters. For example: 'u', 't', etc.
 307      * @param newLocalPatternChars the new localized date-time
 308      * pattern characters.
 309      * @stable ICU 2.0
 310      */
 311     void setLocalPatternChars(const UnicodeString& newLocalPatternChars);
 312
 313     /**
 314      * Returns the locale for this object. Two flavors are available:
 315      * valid and actual locale.
 316      * @draft ICU 2.8 likely to change in ICU 3.0, based on feedback
 317      */
 318     Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
 319
 320     /**
 321      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 322      *
 323      * @stable ICU 2.2
 324      */
 325     virtual UClassID getDynamicClassID() const;
 326
 327     /**
 328      * ICU "poor man's RTTI", returns a UClassID for this class.
 329      *
 330      * @stable ICU 2.2
 331      */
 332     static UClassID U_EXPORT2 getStaticClassID();
 333
 334 private:
 335
 336     friend class SimpleDateFormat;
 337     friend class DateFormatSymbolsSingleSetter; // see udat.cpp
 338
 339     /**
 340      * Era strings. For example: "AD" and "BC".
 341      */
 342     UnicodeString*  fEras;
 343     int32_t         fErasCount;
 344
 345     /**
 346      * Month strings. For example: "January", "February", etc.
 347      */
 348     UnicodeString*  fMonths;
 349     int32_t         fMonthsCount;
 350
 351     /**
 352      * Short month strings. For example: "Jan", "Feb", etc.
 353      */
 354     UnicodeString*  fShortMonths;
 355     int32_t         fShortMonthsCount;
 356
 357     /**
 358      * Weekday strings. For example: "Sunday", "Monday", etc.
 359      */
 360     UnicodeString*  fWeekdays;
 361     int32_t         fWeekdaysCount;
 362
 363     /**
 364      * Short weekday strings. For example: "Sun", "Mon", etc.
 365      */
 366     UnicodeString*  fShortWeekdays;
 367     int32_t         fShortWeekdaysCount;
 368
 369     /**
 370      * Ampm strings. For example: "AM" and "PM".
 371      */
 372     UnicodeString*  fAmPms;
 373     int32_t         fAmPmsCount;
 374
 375     /**
 376      * The format data of all the timezones in this locale.
 377      */
 378     UnicodeString** fZoneStrings;
 379     int32_t         fZoneStringsRowCount;
 380     int32_t         fZoneStringsColCount;
 381
 382     /**
 383      * Localized date-time pattern characters. For example: use 'u' as 'y'.
 384      */
 385     UnicodeString   fLocalPatternChars;
 386
 387 private:
 388     /** valid/actual locale information
 389      *  these are always ICU locales, so the length should not be a problem
 390      */
 391     char validLocale[ULOC_FULLNAME_CAPACITY];
 392     char actualLocale[ULOC_FULLNAME_CAPACITY];
 393
 394
 395     /* Sizes for the last resort string arrays */
 396     typedef enum LastResortSize {
 397         kMonthNum = 13,
 398         kMonthLen = 3,
 399
 400         kDayNum = 8,
 401         kDayLen = 2,
 402
 403         kAmPmNum = 2,
 404         kAmPmLen = 3,
 405
 406         kEraNum = 2,
 407         kEraLen = 3,
 408
 409         kZoneNum = 5,
 410         kZoneLen = 4
 411     } LastResortSize;
 412
 413     DateFormatSymbols(); // default constructor not implemented
 414
 415     void initField(UnicodeString **field, int32_t& length, const UResourceBundle *data, UErrorCode &status);
 416     void initField(UnicodeString **field, int32_t& length, const UChar *data, LastResortSize numStr, LastResortSize strLen, UErrorCode &status);
 417
 418     /**
 419      * Called by the constructors to actually load data from the resources
 420      *
 421      * @param locale               The locale to get symbols for.
 422      * @param type                 Calendar Type (as from Calendar::getType())
 423      * @param status               Input/output parameter, set to success or
 424      *                             failure code upon return.
 425      * @param useLastResortData    determine if use last resort data
 426      */
 427     void initializeData(const Locale&, const char *type, UErrorCode& status, UBool useLastResortData = FALSE);
 428
 429     /**
 430      * Copy or alias an array in another object, as appropriate.
 431      *
 432      * @param dstArray    the copy destination array.
 433      * @param dstCount    fill in with the lenth of 'dstArray'.
 434      * @param srcArray    the source array to be copied.
 435      * @param srcCount    the length of items to be copied from the 'srcArray'.
 436      */
 437     static void assignArray(UnicodeString*& dstArray,
 438                             int32_t& dstCount,
 439                             const UnicodeString* srcArray,
 440                             int32_t srcCount);
 441
 442     /**
 443      * Return true if the given arrays' contents are equal, or if the arrays are
 444      * identical (pointers are equal).
 445      *
 446      * @param array1   one array to be compared with.
 447      * @param array2   another array to be compared with.
 448      * @param count    the length of items to be copied.
 449      * @return         true if the given arrays' contents are equal, or if the arrays are
 450      *                 identical (pointers are equal).
 451      */
 452     static UBool arrayCompare(const UnicodeString* array1,
 453                              const UnicodeString* array2,
 454                              int32_t count);
 455
 456     /**
 457      * Create a copy, in fZoneStrings, of the given zone strings array. The
 458      * member variables fZoneStringsRowCount and fZoneStringsColCount should be
 459      * set already by the caller.
 460      */
 461     void createZoneStrings(const UnicodeString *const * otherStrings);
 462
 463     /**
 464      * Package private: used by SimpleDateFormat
 465      * Gets the index for the given time zone ID to obtain the timezone
 466      * strings for formatting. The time zone ID is just for programmatic
 467      * lookup. NOT LOCALIZED!!!
 468      * @param ID the given time zone ID.
 469      * @return the index of the given time zone ID.  Returns -1 if
 470      * the given time zone ID can't be located in the DateFormatSymbols object.
 471      * @see java.util.SimpleTimeZone
 472      */
 473     int32_t getZoneIndex(const UnicodeString& ID) const;
 474
 475     // Internal method; see source for documentation
 476     int32_t _getZoneIndex(const UnicodeString& id) const;
 477
 478     /**
 479      * Delete all the storage owned by this object.
 480      */
 481     void dispose(void);
 482
 483     /**
 484      * Copy all of the other's data to this.
 485      * @param other the object to be copied.
 486      */
 487     void copyData(const DateFormatSymbols& other);
 488
 489     /**
 490      * Delete just the zone strings.
 491      */
 492     void disposeZoneStrings(void);
 493 };
 494
 495 U_NAMESPACE_END
 496
 497 #endif /* #if !UCONFIG_NO_FORMATTING */
 498
 499 #endif // _DTFMTSYM
 500 //eof