icuSources/i18n/unicode/format.h

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