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
46U_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 the Unicode replacement character
88 * 0xFFFD is returned.
89 * <P>
90 * If there is no match when parsing, a parse failure UErrorCode is
91 * retured 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 */
98class U_I18N_API Format : public UObject {
99public:
100
101 /** Destructor
102 * @stable ICU 2.4
103 */
104 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 virtual UBool 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 UBool 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 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 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 virtual UnicodeString& format(const Formattable& obj,
164 UnicodeString& appendTo,
165 FieldPosition& pos,
166 UErrorCode& status) const = 0;
167 /**
168 * Format an object to produce a string. Subclasses should override this
169 * method. This method allows polymorphic formatting of Formattable objects.
170 * If a subclass of Format receives a Formattable object type it doesn't
171 * handle (e.g., if a numeric Formattable is passed to a DateFormat object)
172 * then it returns a failing UErrorCode.
173 *
174 * @param obj The object to format.
175 * @param appendTo Output parameter to receive result.
176 * Result is appended to existing contents.
177 * @param posIter On return, can be used to iterate over positions
178 * of fields generated by this format call.
179 * @param status Output param filled with success/failure status.
180 * @return Reference to 'appendTo' parameter.
181 * @stable ICU 4.4
182 */
183 virtual UnicodeString& format(const Formattable& obj,
184 UnicodeString& appendTo,
185 FieldPositionIterator* posIter,
186 UErrorCode& status) const;
187
188 /**
189 * Parse a string to produce an object. This is a pure virtual
190 * method which subclasses must implement. This method allows
191 * polymorphic parsing of strings into Formattable objects.
192 * <P>
193 * Before calling, set parse_pos.index to the offset you want to
194 * start parsing at in the source. After calling, parse_pos.index
195 * is the end of the text you parsed. If error occurs, index is
196 * unchanged.
197 * <P>
198 * When parsing, leading whitespace is discarded (with successful
199 * parse), while trailing whitespace is left as is.
200 * <P>
201 * Example:
202 * <P>
203 * Parsing "_12_xy" (where _ represents a space) for a number,
204 * with index == 0 will result in the number 12, with
205 * parse_pos.index updated to 3 (just before the second space).
206 * Parsing a second time will result in a failing UErrorCode since
207 * "xy" is not a number, and leave index at 3.
208 * <P>
209 * Subclasses will typically supply specific parse methods that
210 * return different types of values. Since methods can't overload
211 * on return types, these will typically be named "parse", while
212 * this polymorphic method will always be called parseObject. Any
213 * parse method that does not take a parse_pos should set status
214 * to an error value when no text in the required format is at the
215 * start position.
216 *
217 * @param source The string to be parsed into an object.
218 * @param result Formattable to be set to the parse result.
219 * If parse fails, return contents are undefined.
220 * @param parse_pos The position to start parsing at. Upon return
221 * this param is set to the position after the
222 * last character successfully parsed. If the
223 * source is not parsed successfully, this param
224 * will remain unchanged.
225 * @stable ICU 2.0
226 */
227 virtual void parseObject(const UnicodeString& source,
228 Formattable& result,
229 ParsePosition& parse_pos) const = 0;
230
231 /**
232 * Parses a string to produce an object. This is a convenience method
233 * which calls the pure virtual parseObject() method, and returns a
234 * failure UErrorCode if the ParsePosition indicates failure.
235 *
236 * @param source The string to be parsed into an object.
237 * @param result Formattable to be set to the parse result.
238 * If parse fails, return contents are undefined.
239 * @param status Output param to be filled with success/failure
240 * result code.
241 * @stable ICU 2.0
242 */
243 void parseObject(const UnicodeString& source,
244 Formattable& result,
245 UErrorCode& status) const;
246
247 /** Get the locale for this format object. You can choose between valid and actual locale.
248 * @param type type of the locale we're looking for (valid or actual)
249 * @param status error code for the operation
250 * @return the locale
251 * @stable ICU 2.8
252 */
253 Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
254
255#ifndef U_HIDE_INTERNAL_API
256 /** Get the locale for this format object. You can choose between valid and actual locale.
257 * @param type type of the locale we're looking for (valid or actual)
258 * @param status error code for the operation
259 * @return the locale
260 * @internal
261 */
262 const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
263#endif /* U_HIDE_INTERNAL_API */
264
265 protected:
266 /** @stable ICU 2.8 */
267 void setLocaleIDs(const char* valid, const char* actual);
268
269protected:
270 /**
271 * Default constructor for subclass use only. Does nothing.
272 * @stable ICU 2.0
273 */
274 Format();
275
276 /**
277 * @stable ICU 2.0
278 */
279 Format(const Format&); // Does nothing; for subclasses only
280
281 /**
282 * @stable ICU 2.0
283 */
284 Format& operator=(const Format&); // Does nothing; for subclasses
285
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 occured
292 * @param parseError The UParseError object to fill in
293 * @stable ICU 2.4
294 */
295 static void syntaxError(const UnicodeString& pattern,
296 int32_t pos,
297 UParseError& parseError);
298
299 private:
300 char actualLocale[ULOC_FULLNAME_CAPACITY];
301 char validLocale[ULOC_FULLNAME_CAPACITY];
302};
303
304U_NAMESPACE_END
305
306#endif /* #if !UCONFIG_NO_FORMATTING */
307
308#endif /* U_SHOW_CPLUSPLUS_API */
309
310#endif // _FORMAT
311//eof
312