diff options
Diffstat (limited to 'deps/icu-small/source/i18n/unicode/format.h')
| -rw-r--r-- | deps/icu-small/source/i18n/unicode/format.h | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/deps/icu-small/source/i18n/unicode/format.h b/deps/icu-small/source/i18n/unicode/format.h new file mode 100644 index 0000000000..7bbd32df6a --- /dev/null +++ b/deps/icu-small/source/i18n/unicode/format.h @@ -0,0 +1,305 @@ +/* +******************************************************************************** +* Copyright (C) 1997-2011, International Business Machines Corporation and others. +* All Rights Reserved. +******************************************************************************** +* +* File FORMAT.H +* +* Modification History: +* +* Date Name Description +* 02/19/97 aliu Converted from java. +* 03/17/97 clhuang Updated per C++ implementation. +* 03/27/97 helena Updated to pass the simple test after code review. +******************************************************************************** +*/ +// ***************************************************************************** +// This file was generated from the java source file Format.java +// ***************************************************************************** + +#ifndef FORMAT_H +#define FORMAT_H + + +#include "unicode/utypes.h" + +/** + * \file + * \brief C++ API: Base class for all formats. + */ + +#if !UCONFIG_NO_FORMATTING + +#include "unicode/unistr.h" +#include "unicode/fmtable.h" +#include "unicode/fieldpos.h" +#include "unicode/fpositer.h" +#include "unicode/parsepos.h" +#include "unicode/parseerr.h" +#include "unicode/locid.h" + +U_NAMESPACE_BEGIN + +/** + * Base class for all formats. This is an abstract base class which + * specifies the protocol for classes which convert other objects or + * values, such as numeric values and dates, and their string + * representations. In some cases these representations may be + * localized or contain localized characters or strings. For example, + * a numeric formatter such as DecimalFormat may convert a numeric + * value such as 12345 to the string "$12,345". It may also parse + * the string back into a numeric value. A date and time formatter + * like SimpleDateFormat may represent a specific date, encoded + * numerically, as a string such as "Wednesday, February 26, 1997 AD". + * <P> + * Many of the concrete subclasses of Format employ the notion of + * a pattern. A pattern is a string representation of the rules which + * govern the interconversion between values and strings. For example, + * a DecimalFormat object may be associated with the pattern + * "$#,##0.00;($#,##0.00)", which is a common US English format for + * currency values, yielding strings such as "$1,234.45" for 1234.45, + * and "($987.65)" for 987.6543. The specific syntax of a pattern + * is defined by each subclass. + * <P> + * Even though many subclasses use patterns, the notion of a pattern + * is not inherent to Format classes in general, and is not part of + * the explicit base class protocol. + * <P> + * Two complex formatting classes bear mentioning. These are + * MessageFormat and ChoiceFormat. ChoiceFormat is a subclass of + * NumberFormat which allows the user to format different number ranges + * as strings. For instance, 0 may be represented as "no files", 1 as + * "one file", and any number greater than 1 as "many files". + * MessageFormat is a formatter which utilizes other Format objects to + * format a string containing with multiple values. For instance, + * A MessageFormat object might produce the string "There are no files + * on the disk MyDisk on February 27, 1997." given the arguments 0, + * "MyDisk", and the date value of 2/27/97. See the ChoiceFormat + * and MessageFormat headers for further information. + * <P> + * If formatting is unsuccessful, a failing UErrorCode is returned when + * the Format cannot format the type of object, otherwise if there is + * something illformed about the the Unicode replacement character + * 0xFFFD is returned. + * <P> + * If there is no match when parsing, a parse failure UErrorCode is + * retured for methods which take no ParsePosition. For the method + * that takes a ParsePosition, the index parameter is left unchanged. + * <P> + * <em>User subclasses are not supported.</em> While clients may write + * subclasses, such code will not necessarily work and will not be + * guaranteed to work stably from release to release. + */ +class U_I18N_API Format : public UObject { +public: + + /** Destructor + * @stable ICU 2.4 + */ + virtual ~Format(); + + /** + * Return true if the given Format objects are semantically equal. + * Objects of different subclasses are considered unequal. + * @param other the object to be compared with. + * @return Return true if the given Format objects are semantically equal. + * Objects of different subclasses are considered unequal. + * @stable ICU 2.0 + */ + virtual UBool operator==(const Format& other) const = 0; + + /** + * Return true if the given Format objects are not semantically + * equal. + * @param other the object to be compared with. + * @return Return true if the given Format objects are not semantically. + * @stable ICU 2.0 + */ + UBool operator!=(const Format& other) const { return !operator==(other); } + + /** + * Clone this object polymorphically. The caller is responsible + * for deleting the result when done. + * @return A copy of the object + * @stable ICU 2.0 + */ + virtual Format* clone() const = 0; + + /** + * Formats an object to produce a string. + * + * @param obj The object to format. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param status Output parameter filled in with success or failure status. + * @return Reference to 'appendTo' parameter. + * @stable ICU 2.0 + */ + UnicodeString& format(const Formattable& obj, + UnicodeString& appendTo, + UErrorCode& status) const; + + /** + * Format an object to produce a string. This is a pure virtual method which + * subclasses must implement. This method allows polymorphic formatting + * of Formattable objects. If a subclass of Format receives a Formattable + * object type it doesn't handle (e.g., if a numeric Formattable is passed + * to a DateFormat object) then it returns a failing UErrorCode. + * + * @param obj The object to format. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param pos On input: an alignment field, if desired. + * On output: the offsets of the alignment field. + * @param status Output param filled with success/failure status. + * @return Reference to 'appendTo' parameter. + * @stable ICU 2.0 + */ + virtual UnicodeString& format(const Formattable& obj, + UnicodeString& appendTo, + FieldPosition& pos, + UErrorCode& status) const = 0; + /** + * Format an object to produce a string. Subclasses should override this + * method. This method allows polymorphic formatting of Formattable objects. + * If a subclass of Format receives a Formattable object type it doesn't + * handle (e.g., if a numeric Formattable is passed to a DateFormat object) + * then it returns a failing UErrorCode. + * + * @param obj The object to format. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param posIter On return, can be used to iterate over positions + * of fields generated by this format call. + * @param status Output param filled with success/failure status. + * @return Reference to 'appendTo' parameter. + * @stable ICU 4.4 + */ + virtual UnicodeString& format(const Formattable& obj, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; + + /** + * Parse a string to produce an object. This is a pure virtual + * method which subclasses must implement. This method allows + * polymorphic parsing of strings into Formattable objects. + * <P> + * Before calling, set parse_pos.index to the offset you want to + * start parsing at in the source. After calling, parse_pos.index + * is the end of the text you parsed. If error occurs, index is + * unchanged. + * <P> + * When parsing, leading whitespace is discarded (with successful + * parse), while trailing whitespace is left as is. + * <P> + * Example: + * <P> + * Parsing "_12_xy" (where _ represents a space) for a number, + * with index == 0 will result in the number 12, with + * parse_pos.index updated to 3 (just before the second space). + * Parsing a second time will result in a failing UErrorCode since + * "xy" is not a number, and leave index at 3. + * <P> + * Subclasses will typically supply specific parse methods that + * return different types of values. Since methods can't overload + * on return types, these will typically be named "parse", while + * this polymorphic method will always be called parseObject. Any + * parse method that does not take a parse_pos should set status + * to an error value when no text in the required format is at the + * start position. + * + * @param source The string to be parsed into an object. + * @param result Formattable to be set to the parse result. + * If parse fails, return contents are undefined. + * @param parse_pos The position to start parsing at. Upon return + * this param is set to the position after the + * last character successfully parsed. If the + * source is not parsed successfully, this param + * will remain unchanged. + * @stable ICU 2.0 + */ + virtual void parseObject(const UnicodeString& source, + Formattable& result, + ParsePosition& parse_pos) const = 0; + + /** + * Parses a string to produce an object. This is a convenience method + * which calls the pure virtual parseObject() method, and returns a + * failure UErrorCode if the ParsePosition indicates failure. + * + * @param source The string to be parsed into an object. + * @param result Formattable to be set to the parse result. + * If parse fails, return contents are undefined. + * @param status Output param to be filled with success/failure + * result code. + * @stable ICU 2.0 + */ + void parseObject(const UnicodeString& source, + Formattable& result, + UErrorCode& status) const; + + /** Get the locale for this format object. You can choose between valid and actual locale. + * @param type type of the locale we're looking for (valid or actual) + * @param status error code for the operation + * @return the locale + * @stable ICU 2.8 + */ + Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; + +#ifndef U_HIDE_INTERNAL_API + /** Get the locale for this format object. You can choose between valid and actual locale. + * @param type type of the locale we're looking for (valid or actual) + * @param status error code for the operation + * @return the locale + * @internal + */ + const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const; +#endif /* U_HIDE_INTERNAL_API */ + + protected: + /** @stable ICU 2.8 */ + void setLocaleIDs(const char* valid, const char* actual); + +protected: + /** + * Default constructor for subclass use only. Does nothing. + * @stable ICU 2.0 + */ + Format(); + + /** + * @stable ICU 2.0 + */ + Format(const Format&); // Does nothing; for subclasses only + + /** + * @stable ICU 2.0 + */ + Format& operator=(const Format&); // Does nothing; for subclasses + + + /** + * Simple function for initializing a UParseError from a UnicodeString. + * + * @param pattern The pattern to copy into the parseError + * @param pos The position in pattern where the error occured + * @param parseError The UParseError object to fill in + * @stable ICU 2.4 + */ + static void syntaxError(const UnicodeString& pattern, + int32_t pos, + UParseError& parseError); + + private: + char actualLocale[ULOC_FULLNAME_CAPACITY]; + char validLocale[ULOC_FULLNAME_CAPACITY]; +}; + +U_NAMESPACE_END + +#endif /* #if !UCONFIG_NO_FORMATTING */ + +#endif // _FORMAT +//eof |