The Tor Browser / file comparison

comparison: intl/icu/source/i18n/unicode/format.h

intl/icu/source/i18n/unicode/format.h

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

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial