icuSources/i18n/unicode/format.h

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