[apple/icu.git] / icuSources / i18n / unicode / format.h

/*
********************************************************************************
* Copyright (C) {1997-2004}, 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"

#if !UCONFIG_NO_FORMATTING

#include "unicode/unistr.h"
#include "unicode/fmtable.h"
#include "unicode/fieldpos.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;

    /**
     * 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;

    /**
     * Returns a unique class ID POLYMORPHICALLY.  Pure virtual method.
     * This method is to implement a simple version of RTTI, since not all
     * C++ compilers support genuine RTTI.  Polymorphic operator==() and
     * clone() methods call this method.
     * Concrete subclasses of Format must implement getDynamicClassID()
     *
     * @return          The class ID for this object. All objects of a
     *                  given class have the same class ID.  Objects of
     *                  other classes have different class IDs.
     * @stable ICU 2.0
     */
    virtual UClassID getDynamicClassID() const = 0;

    /** 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
     *  @draft ICU 2.8 likely to change in ICU 3.0, based on feedback
     */
    Locale getLocale(ULocDataLocaleType type, 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
     *  @internal
     */
    const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;

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