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