/src/icu/icu4c/source/i18n/unicode/format.h

Source
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
********************************************************************************
* 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"

#if U_SHOW_CPLUSPLUS_API

/**
 * \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 Unicode replacement character
 * 0xFFFD is returned.
 * <P>
 * If there is no match when parsing, a parse failure UErrorCode is
 * returned 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_CLASS Format : public UObject {
public:

    /** Destructor
     * @stable ICU 2.4
     */
    U_I18N_API 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
     */
    U_I18N_API virtual bool 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
     */
    U_I18N_API bool 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
     */
    U_I18N_API 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
     */
    U_I18N_API 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
     */
    U_I18N_API 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
     */
    U_I18N_API 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
     */
    U_I18N_API 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
     */
    U_I18N_API 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
     */
    U_I18N_API 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
     */
    U_I18N_API const char* getLocaleID(ULocDataLocaleType type, UErrorCode& status) const;
#endif  /* U_HIDE_INTERNAL_API */

 protected:
    /** @stable ICU 2.8 */
    U_I18N_API void setLocaleIDs(const char* valid, const char* actual);

protected:
    /**
     * Default constructor for subclass use only.  Does nothing.
     * @stable ICU 2.0
     */
    U_I18N_API Format();

    /**
     * @stable ICU 2.0
     */
    U_I18N_API Format(const Format&); // Does nothing; for subclasses only

    /**
     * @stable ICU 2.0
     */
    U_I18N_API 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 occurred
     * @param parseError The UParseError object to fill in
     * @stable ICU 2.4
     */
    U_I18N_API static void syntaxError(const UnicodeString& pattern,
                                       int32_t pos,
                                       UParseError& parseError);

 private:
    Locale actualLocale;
    Locale validLocale;
};

U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif /* U_SHOW_CPLUSPLUS_API */

#endif // _FORMAT
//eof

Coverage Report

Created: 2025-10-24 06:54

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