Home | History | Annotate | Download | only in unicode
      1 /*
      2 ********************************************************************************
      3 * Copyright (C) 1997-2010, 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     /** Get the locale for this format object. You can choose between valid and actual locale.
    252      *  @param type type of the locale we're looking for (valid or actual)
    253      *  @param status error code for the operation
    254      *  @return the locale
    255      *  @internal
    256      */
    257     const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
    258 
    259  protected:
    260     /** @stable ICU 2.8 */
    261     void setLocaleIDs(const char* valid, const char* actual);
    262 
    263 protected:
    264     /**
    265      * Default constructor for subclass use only.  Does nothing.
    266      * @stable ICU 2.0
    267      */
    268     Format();
    269 
    270     /**
    271      * @stable ICU 2.0
    272      */
    273     Format(const Format&); // Does nothing; for subclasses only
    274 
    275     /**
    276      * @stable ICU 2.0
    277      */
    278     Format& operator=(const Format&); // Does nothing; for subclasses
    279 
    280 
    281     /**
    282      * Simple function for initializing a UParseError from a UnicodeString.
    283      *
    284      * @param pattern The pattern to copy into the parseError
    285      * @param pos The position in pattern where the error occured
    286      * @param parseError The UParseError object to fill in
    287      * @stable ICU 2.4
    288      */
    289     static void syntaxError(const UnicodeString& pattern,
    290                             int32_t pos,
    291                             UParseError& parseError);
    292 
    293  private:
    294     char actualLocale[ULOC_FULLNAME_CAPACITY];
    295     char validLocale[ULOC_FULLNAME_CAPACITY];
    296 };
    297 
    298 U_NAMESPACE_END
    299 
    300 #endif /* #if !UCONFIG_NO_FORMATTING */
    301 
    302 #endif // _FORMAT
    303 //eof
    304