icuSources/i18n/unicode/format.h

   1 /*
   2 ********************************************************************************
   3 * Copyright (C) {1997-2004}, International Business Machines Corporation and others. All Rights Reserved.
   4 ********************************************************************************
   5 *
   6 * File FORMAT.H
   7 *
   8 * Modification History:
   9 *
  10 *   Date        Name        Description
  11 *   02/19/97    aliu        Converted from java.
  12 *   03/17/97    clhuang     Updated per C++ implementation.
  13 *   03/27/97    helena      Updated to pass the simple test after code review.
  14 ********************************************************************************
  15 */
  16 // *****************************************************************************
  17 // This file was generated from the java source file Format.java
  18 // *****************************************************************************
  19
  20 #ifndef FORMAT_H
  21 #define FORMAT_H
  22
  23
  24 #include "unicode/utypes.h"
  25
  26 #if !UCONFIG_NO_FORMATTING
  27
  28 #include "unicode/unistr.h"
  29 #include "unicode/fmtable.h"
  30 #include "unicode/fieldpos.h"
  31 #include "unicode/parsepos.h"
  32 #include "unicode/parseerr.h"
  33 #include "unicode/locid.h"
  34
  35 U_NAMESPACE_BEGIN
  36
  37 /**
  38  * Base class for all formats.  This is an abstract base class which
  39  * specifies the protocol for classes which convert other objects or
  40  * values, such as numeric values and dates, and their string
  41  * representations.  In some cases these representations may be
  42  * localized or contain localized characters or strings.  For example,
  43  * a numeric formatter such as DecimalFormat may convert a numeric
  44  * value such as 12345 to the string "$12,345".  It may also parse
  45  * the string back into a numeric value.  A date and time formatter
  46  * like SimpleDateFormat may represent a specific date, encoded
  47  * numerically, as a string such as "Wednesday, February 26, 1997 AD".
  48  * <P>
  49  * Many of the concrete subclasses of Format employ the notion of
  50  * a pattern.  A pattern is a string representation of the rules which
  51  * govern the interconversion between values and strings.  For example,
  52  * a DecimalFormat object may be associated with the pattern
  53  * "$#,##0.00;($#,##0.00)", which is a common US English format for
  54  * currency values, yielding strings such as "$1,234.45" for 1234.45,
  55  * and "($987.65)" for 987.6543.  The specific syntax of a pattern
  56  * is defined by each subclass.
  57  * <P>
  58  * Even though many subclasses use patterns, the notion of a pattern
  59  * is not inherent to Format classes in general, and is not part of
  60  * the explicit base class protocol.
  61  * <P>
  62  * Two complex formatting classes bear mentioning.  These are
  63  * MessageFormat and ChoiceFormat.  ChoiceFormat is a subclass of
  64  * NumberFormat which allows the user to format different number ranges
  65  * as strings.  For instance, 0 may be represented as "no files", 1 as
  66  * "one file", and any number greater than 1 as "many files".
  67  * MessageFormat is a formatter which utilizes other Format objects to
  68  * format a string containing with multiple values.  For instance,
  69  * A MessageFormat object might produce the string "There are no files
  70  * on the disk MyDisk on February 27, 1997." given the arguments 0,
  71  * "MyDisk", and the date value of 2/27/97.  See the ChoiceFormat
  72  * and MessageFormat headers for further information.
  73  * <P>
  74  * If formatting is unsuccessful, a failing UErrorCode is returned when
  75  * the Format cannot format the type of object, otherwise if there is
  76  * something illformed about the the Unicode replacement character
  77  * 0xFFFD is returned.
  78  * <P>
  79  * If there is no match when parsing, a parse failure UErrorCode is
  80  * retured for methods which take no ParsePosition.  For the method
  81  * that takes a ParsePosition, the index parameter is left unchanged.
  82  * <P>
  83  * <em>User subclasses are not supported.</em> While clients may write
  84  * subclasses, such code will not necessarily work and will not be
  85  * guaranteed to work stably from release to release.
  86  */
  87 class U_I18N_API Format : public UObject {
  88 public:
  89
  90     /** Destructor
  91      * @stable ICU 2.4
  92      */
  93     virtual ~Format();
  94
  95     /**
  96      * Return true if the given Format objects are semantically equal.
  97      * Objects of different subclasses are considered unequal.
  98      * @param other    the object to be compared with.
  99      * @return         Return true if the given Format objects are semantically equal.
 100      *                 Objects of different subclasses are considered unequal.
 101      * @stable ICU 2.0
 102      */
 103     virtual UBool operator==(const Format& other) const = 0;
 104
 105     /**
 106      * Return true if the given Format objects are not semantically
 107      * equal.
 108      * @param other    the object to be compared with.
 109      * @return         Return true if the given Format objects are not semantically.
 110      * @stable ICU 2.0
 111      */
 112     UBool operator!=(const Format& other) const { return !operator==(other); }
 113
 114     /**
 115      * Clone this object polymorphically.  The caller is responsible
 116      * for deleting the result when done.
 117      * @return    A copy of the object
 118      * @stable ICU 2.0
 119      */
 120     virtual Format* clone() const = 0;
 121
 122     /**
 123      * Formats an object to produce a string.
 124      *
 125      * @param obj       The object to format.
 126      * @param appendTo  Output parameter to receive result.
 127      *                  Result is appended to existing contents.
 128      * @param status    Output parameter filled in with success or failure status.
 129      * @return          Reference to 'appendTo' parameter.
 130      * @stable ICU 2.0
 131      */
 132     UnicodeString& format(const Formattable& obj,
 133                           UnicodeString& appendTo,
 134                           UErrorCode& status) const;
 135
 136     /**
 137      * Format an object to produce a string.  This is a pure virtual method which
 138      * subclasses must implement. This method allows polymorphic formatting
 139      * of Formattable objects. If a subclass of Format receives a Formattable
 140      * object type it doesn't handle (e.g., if a numeric Formattable is passed
 141      * to a DateFormat object) then it returns a failing UErrorCode.
 142      *
 143      * @param obj       The object to format.
 144      * @param appendTo  Output parameter to receive result.
 145      *                  Result is appended to existing contents.
 146      * @param pos       On input: an alignment field, if desired.
 147      *                  On output: the offsets of the alignment field.
 148      * @param status    Output param filled with success/failure status.
 149      * @return          Reference to 'appendTo' parameter.
 150      * @stable ICU 2.0
 151      */
 152     virtual UnicodeString& format(const Formattable& obj,
 153                                   UnicodeString& appendTo,
 154                                   FieldPosition& pos,
 155                                   UErrorCode& status) const = 0;
 156
 157     /**
 158      * Parse a string to produce an object.  This is a pure virtual
 159      * method which subclasses must implement.  This method allows
 160      * polymorphic parsing of strings into Formattable objects.
 161      * <P>
 162      * Before calling, set parse_pos.index to the offset you want to
 163      * start parsing at in the source.  After calling, parse_pos.index
 164      * is the end of the text you parsed.  If error occurs, index is
 165      * unchanged.
 166      * <P>
 167      * When parsing, leading whitespace is discarded (with successful
 168      * parse), while trailing whitespace is left as is.
 169      * <P>
 170      * Example:
 171      * <P>
 172      * Parsing "_12_xy" (where _ represents a space) for a number,
 173      * with index == 0 will result in the number 12, with
 174      * parse_pos.index updated to 3 (just before the second space).
 175      * Parsing a second time will result in a failing UErrorCode since
 176      * "xy" is not a number, and leave index at 3.
 177      * <P>
 178      * Subclasses will typically supply specific parse methods that
 179      * return different types of values. Since methods can't overload
 180      * on return types, these will typically be named "parse", while
 181      * this polymorphic method will always be called parseObject.  Any
 182      * parse method that does not take a parse_pos should set status
 183      * to an error value when no text in the required format is at the
 184      * start position.
 185      *
 186      * @param source    The string to be parsed into an object.
 187      * @param result    Formattable to be set to the parse result.
 188      *                  If parse fails, return contents are undefined.
 189      * @param parse_pos The position to start parsing at. Upon return
 190      *                  this param is set to the position after the
 191      *                  last character successfully parsed. If the
 192      *                  source is not parsed successfully, this param
 193      *                  will remain unchanged.
 194      * @stable ICU 2.0
 195      */
 196     virtual void parseObject(const UnicodeString& source,
 197                              Formattable& result,
 198                              ParsePosition& parse_pos) const = 0;
 199
 200     /**
 201      * Parses a string to produce an object. This is a convenience method
 202      * which calls the pure virtual parseObject() method, and returns a
 203      * failure UErrorCode if the ParsePosition indicates failure.
 204      *
 205      * @param source    The string to be parsed into an object.
 206      * @param result    Formattable to be set to the parse result.
 207      *                  If parse fails, return contents are undefined.
 208      * @param status    Output param to be filled with success/failure
 209      *                  result code.
 210      * @stable ICU 2.0
 211      */
 212     void parseObject(const UnicodeString& source,
 213                      Formattable& result,
 214                      UErrorCode& status) const;
 215
 216     /**
 217      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual method.
 218      * This method is to implement a simple version of RTTI, since not all
 219      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
 220      * clone() methods call this method.
 221      * Concrete subclasses of Format must implement getDynamicClassID()
 222      *
 223      * @return          The class ID for this object. All objects of a
 224      *                  given class have the same class ID.  Objects of
 225      *                  other classes have different class IDs.
 226      * @stable ICU 2.0
 227      */
 228     virtual UClassID getDynamicClassID() const = 0;
 229
 230     /** Get the locale for this format object. You can choose between valid and actual locale.
 231      *  @param type type of the locale we're looking for (valid or actual)
 232      *  @param status error code for the operation
 233      *  @return the locale
 234      *  @draft ICU 2.8 likely to change in ICU 3.0, based on feedback
 235      */
 236     Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
 237
 238     /** Get the locale for this format object. You can choose between valid and actual locale.
 239      *  @param type type of the locale we're looking for (valid or actual)
 240      *  @param status error code for the operation
 241      *  @return the locale
 242      *  @internal
 243      */
 244     const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
 245
 246  protected:
 247     /** @draft ICU 2.8 */
 248     void setLocaleIDs(const char* valid, const char* actual);
 249
 250 protected:
 251     /**
 252      * Default constructor for subclass use only.  Does nothing.
 253      * @stable ICU 2.0
 254      */
 255     Format();
 256
 257     /**
 258      * @stable ICU 2.0
 259      */
 260     Format(const Format&); // Does nothing; for subclasses only
 261
 262     /**
 263      * @stable ICU 2.0
 264      */
 265     Format& operator=(const Format&); // Does nothing; for subclasses
 266
 267
 268     /**
 269      * Simple function for initializing a UParseError from a UnicodeString.
 270      *
 271      * @param pattern The pattern to copy into the parseError
 272      * @param pos The position in pattern where the error occured
 273      * @param parseError The UParseError object to fill in
 274      * @stable ICU 2.4
 275      */
 276     static void syntaxError(const UnicodeString& pattern,
 277                             int32_t pos,
 278                             UParseError& parseError);
 279
 280  private:
 281     char actualLocale[ULOC_FULLNAME_CAPACITY];
 282     char validLocale[ULOC_FULLNAME_CAPACITY];
 283 };
 284
 285 U_NAMESPACE_END
 286
 287 #endif /* #if !UCONFIG_NO_FORMATTING */
 288
 289 #endif // _FORMAT
 290 //eof