michael@0: * Many of the concrete subclasses of Format employ the notion of michael@0: * a pattern. A pattern is a string representation of the rules which michael@0: * govern the interconversion between values and strings. For example, michael@0: * a DecimalFormat object may be associated with the pattern michael@0: * "$#,##0.00;($#,##0.00)", which is a common US English format for michael@0: * currency values, yielding strings such as "$1,234.45" for 1234.45, michael@0: * and "($987.65)" for 987.6543. The specific syntax of a pattern michael@0: * is defined by each subclass. michael@0: *
michael@0: * Even though many subclasses use patterns, the notion of a pattern michael@0: * is not inherent to Format classes in general, and is not part of michael@0: * the explicit base class protocol. michael@0: *
michael@0: * Two complex formatting classes bear mentioning. These are michael@0: * MessageFormat and ChoiceFormat. ChoiceFormat is a subclass of michael@0: * NumberFormat which allows the user to format different number ranges michael@0: * as strings. For instance, 0 may be represented as "no files", 1 as michael@0: * "one file", and any number greater than 1 as "many files". michael@0: * MessageFormat is a formatter which utilizes other Format objects to michael@0: * format a string containing with multiple values. For instance, michael@0: * A MessageFormat object might produce the string "There are no files michael@0: * on the disk MyDisk on February 27, 1997." given the arguments 0, michael@0: * "MyDisk", and the date value of 2/27/97. See the ChoiceFormat michael@0: * and MessageFormat headers for further information. michael@0: *
michael@0: * If formatting is unsuccessful, a failing UErrorCode is returned when michael@0: * the Format cannot format the type of object, otherwise if there is michael@0: * something illformed about the the Unicode replacement character michael@0: * 0xFFFD is returned. michael@0: *
michael@0: * If there is no match when parsing, a parse failure UErrorCode is michael@0: * retured for methods which take no ParsePosition. For the method michael@0: * that takes a ParsePosition, the index parameter is left unchanged. michael@0: *
michael@0: * User subclasses are not supported. While clients may write michael@0: * subclasses, such code will not necessarily work and will not be michael@0: * guaranteed to work stably from release to release. michael@0: */ michael@0: class U_I18N_API Format : public UObject { michael@0: public: michael@0: michael@0: /** Destructor michael@0: * @stable ICU 2.4 michael@0: */ michael@0: virtual ~Format(); michael@0: michael@0: /** michael@0: * Return true if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * @param other the object to be compared with. michael@0: * @return Return true if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UBool operator==(const Format& other) const = 0; michael@0: michael@0: /** michael@0: * Return true if the given Format objects are not semantically michael@0: * equal. michael@0: * @param other the object to be compared with. michael@0: * @return Return true if the given Format objects are not semantically. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool operator!=(const Format& other) const { return !operator==(other); } michael@0: michael@0: /** michael@0: * Clone this object polymorphically. The caller is responsible michael@0: * for deleting the result when done. michael@0: * @return A copy of the object michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual Format* clone() const = 0; michael@0: michael@0: /** michael@0: * Formats an object to produce a string. michael@0: * michael@0: * @param obj The object to format. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param status Output parameter filled in with success or failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format an object to produce a string. This is a pure virtual method which michael@0: * subclasses must implement. This method allows polymorphic formatting michael@0: * of Formattable objects. If a subclass of Format receives a Formattable michael@0: * object type it doesn't handle (e.g., if a numeric Formattable is passed michael@0: * to a DateFormat object) then it returns a failing UErrorCode. michael@0: * michael@0: * @param obj The object to format. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode& status) const = 0; michael@0: /** michael@0: * Format an object to produce a string. Subclasses should override this michael@0: * method. This method allows polymorphic formatting of Formattable objects. michael@0: * If a subclass of Format receives a Formattable object type it doesn't michael@0: * handle (e.g., if a numeric Formattable is passed to a DateFormat object) michael@0: * then it returns a failing UErrorCode. michael@0: * michael@0: * @param obj The object to format. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 4.4 michael@0: */ michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Parse a string to produce an object. This is a pure virtual michael@0: * method which subclasses must implement. This method allows michael@0: * polymorphic parsing of strings into Formattable objects. michael@0: *
michael@0: * Before calling, set parse_pos.index to the offset you want to michael@0: * start parsing at in the source. After calling, parse_pos.index michael@0: * is the end of the text you parsed. If error occurs, index is michael@0: * unchanged. michael@0: *
michael@0: * When parsing, leading whitespace is discarded (with successful michael@0: * parse), while trailing whitespace is left as is. michael@0: *
michael@0: * Example: michael@0: *
michael@0: * Parsing "_12_xy" (where _ represents a space) for a number, michael@0: * with index == 0 will result in the number 12, with michael@0: * parse_pos.index updated to 3 (just before the second space). michael@0: * Parsing a second time will result in a failing UErrorCode since michael@0: * "xy" is not a number, and leave index at 3. michael@0: *
michael@0: * Subclasses will typically supply specific parse methods that michael@0: * return different types of values. Since methods can't overload michael@0: * on return types, these will typically be named "parse", while michael@0: * this polymorphic method will always be called parseObject. Any michael@0: * parse method that does not take a parse_pos should set status michael@0: * to an error value when no text in the required format is at the michael@0: * start position. michael@0: * michael@0: * @param source The string to be parsed into an object. michael@0: * @param result Formattable to be set to the parse result. michael@0: * If parse fails, return contents are undefined. michael@0: * @param parse_pos The position to start parsing at. Upon return michael@0: * this param is set to the position after the michael@0: * last character successfully parsed. If the michael@0: * source is not parsed successfully, this param michael@0: * will remain unchanged. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void parseObject(const UnicodeString& source, michael@0: Formattable& result, michael@0: ParsePosition& parse_pos) const = 0; michael@0: michael@0: /** michael@0: * Parses a string to produce an object. This is a convenience method michael@0: * which calls the pure virtual parseObject() method, and returns a michael@0: * failure UErrorCode if the ParsePosition indicates failure. michael@0: * michael@0: * @param source The string to be parsed into an object. michael@0: * @param result Formattable to be set to the parse result. michael@0: * If parse fails, return contents are undefined. michael@0: * @param status Output param to be filled with success/failure michael@0: * result code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: void parseObject(const UnicodeString& source, michael@0: Formattable& result, michael@0: UErrorCode& status) const; michael@0: michael@0: /** Get the locale for this format object. You can choose between valid and actual locale. michael@0: * @param type type of the locale we're looking for (valid or actual) michael@0: * @param status error code for the operation michael@0: * @return the locale michael@0: * @stable ICU 2.8 michael@0: */ michael@0: Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** Get the locale for this format object. You can choose between valid and actual locale. michael@0: * @param type type of the locale we're looking for (valid or actual) michael@0: * @param status error code for the operation michael@0: * @return the locale michael@0: * @internal michael@0: */ michael@0: const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: protected: michael@0: /** @stable ICU 2.8 */ michael@0: void setLocaleIDs(const char* valid, const char* actual); michael@0: michael@0: protected: michael@0: /** michael@0: * Default constructor for subclass use only. Does nothing. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Format(); michael@0: michael@0: /** michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Format(const Format&); // Does nothing; for subclasses only michael@0: michael@0: /** michael@0: * @stable ICU 2.0 michael@0: */ michael@0: Format& operator=(const Format&); // Does nothing; for subclasses michael@0: michael@0: michael@0: /** michael@0: * Simple function for initializing a UParseError from a UnicodeString. michael@0: * michael@0: * @param pattern The pattern to copy into the parseError michael@0: * @param pos The position in pattern where the error occured michael@0: * @param parseError The UParseError object to fill in michael@0: * @stable ICU 2.4 michael@0: */ michael@0: static void syntaxError(const UnicodeString& pattern, michael@0: int32_t pos, michael@0: UParseError& parseError); michael@0: michael@0: private: michael@0: char actualLocale[ULOC_FULLNAME_CAPACITY]; michael@0: char validLocale[ULOC_FULLNAME_CAPACITY]; michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */ michael@0: michael@0: #endif // _FORMAT michael@0: //eof