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