icuSources/i18n/unicode/format.h

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