intl/icu/source/i18n/unicode/choicfmt.h@6474c204b198
intl/icu/source/i18n/unicode/choicfmt.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /*
2 ********************************************************************************
3 * Copyright (C) 1997-2013, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 ********************************************************************************
6 *
7 * File CHOICFMT.H
8 *
9 * Modification History:
10 *
11 * Date Name Description
12 * 02/19/97 aliu Converted from java.
13 * 03/20/97 helena Finished first cut of implementation and got rid
14 * of nextDouble/previousDouble and replaced with
15 * boolean array.
16 * 4/10/97 aliu Clean up. Modified to work on AIX.
17 * 8/6/97 nos Removed overloaded constructor, member var 'buffer'.
18 * 07/22/98 stephen Removed operator!= (implemented in Format)
19 ********************************************************************************
20 */
22 #ifndef CHOICFMT_H
23 #define CHOICFMT_H
25 #include "unicode/utypes.h"
27 /**
28 * \file
29 * \brief C++ API: Choice Format.
30 */
32 #if !UCONFIG_NO_FORMATTING
33 #ifndef U_HIDE_DEPRECATED_API
35 #include "unicode/fieldpos.h"
36 #include "unicode/format.h"
37 #include "unicode/messagepattern.h"
38 #include "unicode/numfmt.h"
39 #include "unicode/unistr.h"
41 U_NAMESPACE_BEGIN
43 class MessageFormat;
45 /**
46 * ChoiceFormat converts between ranges of numeric values and strings for those ranges.
47 * The strings must conform to the MessageFormat pattern syntax.
48 *
49 * <p><em><code>ChoiceFormat</code> is probably not what you need.
50 * Please use <code>MessageFormat</code>
51 * with <code>plural</code> arguments for proper plural selection,
52 * and <code>select</code> arguments for simple selection among a fixed set of choices!</em></p>
53 *
54 * <p>A <code>ChoiceFormat</code> splits
55 * the real number line \htmlonly<code>-∞</code> to
56 * <code>+∞</code>\endhtmlonly into two
57 * or more contiguous ranges. Each range is mapped to a
58 * string.</p>
59 *
60 * <p><code>ChoiceFormat</code> was originally intended
61 * for displaying grammatically correct
62 * plurals such as "There is one file." vs. "There are 2 files."
63 * <em>However,</em> plural rules for many languages
64 * are too complex for the capabilities of ChoiceFormat,
65 * and its requirement of specifying the precise rules for each message
66 * is unmanageable for translators.</p>
67 *
68 * <p>There are two methods of defining a <code>ChoiceFormat</code>; both
69 * are equivalent. The first is by using a string pattern. This is the
70 * preferred method in most cases. The second method is through direct
71 * specification of the arrays that logically make up the
72 * <code>ChoiceFormat</code>.</p>
73 *
74 * <p>Note: Typically, choice formatting is done (if done at all) via <code>MessageFormat</code>
75 * with a <code>choice</code> argument type,
76 * rather than using a stand-alone <code>ChoiceFormat</code>.</p>
77 *
78 * <h5>Patterns and Their Interpretation</h5>
79 *
80 * <p>The pattern string defines the range boundaries and the strings for each number range.
81 * Syntax:
82 * <pre>
83 * choiceStyle = number separator message ('|' number separator message)*
84 * number = normal_number | ['-'] \htmlonly∞\endhtmlonly (U+221E, infinity)
85 * normal_number = double value (unlocalized ASCII string)
86 * separator = less_than | less_than_or_equal
87 * less_than = '<'
88 * less_than_or_equal = '#' | \htmlonly≤\endhtmlonly (U+2264)
89 * message: see {@link MessageFormat}
90 * </pre>
91 * Pattern_White_Space between syntax elements is ignored, except
92 * around each range's sub-message.</p>
93 *
94 * <p>Each numeric sub-range extends from the current range's number
95 * to the next range's number.
96 * The number itself is included in its range if a <code>less_than_or_equal</code> sign is used,
97 * and excluded from its range (and instead included in the previous range)
98 * if a <code>less_than</code> sign is used.</p>
99 *
100 * <p>When a <code>ChoiceFormat</code> is constructed from
101 * arrays of numbers, closure flags and strings,
102 * they are interpreted just like
103 * the sequence of <code>(number separator string)</code> in an equivalent pattern string.
104 * <code>closure[i]==TRUE</code> corresponds to a <code>less_than</code> separator sign.
105 * The equivalent pattern string will be constructed automatically.</p>
106 *
107 * <p>During formatting, a number is mapped to the first range
108 * where the number is not greater than the range's upper limit.
109 * That range's message string is returned. A NaN maps to the very first range.</p>
110 *
111 * <p>During parsing, a range is selected for the longest match of
112 * any range's message. That range's number is returned, ignoring the separator/closure.
113 * Only a simple string match is performed, without parsing of arguments that
114 * might be specified in the message strings.</p>
115 *
116 * <p>Note that the first range's number is ignored in formatting
117 * but may be returned from parsing.</p>
118 *
119 * <h5>Examples</h5>
120 *
121 * <p>Here is an example of two arrays that map the number
122 * <code>1..7</code> to the English day of the week abbreviations
123 * <code>Sun..Sat</code>. No closures array is given; this is the same as
124 * specifying all closures to be <code>FALSE</code>.</p>
125 *
126 * <pre> {1,2,3,4,5,6,7},
127 * {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}</pre>
128 *
129 * <p>Here is an example that maps the ranges [-Inf, 1), [1, 1], and (1,
130 * +Inf] to three strings. That is, the number line is split into three
131 * ranges: x < 1.0, x = 1.0, and x > 1.0.
132 * (The round parentheses in the notation above indicate an exclusive boundary,
133 * like the turned bracket in European notation: [-Inf, 1) == [-Inf, 1[ )</p>
134 *
135 * <pre> {0, 1, 1},
136 * {FALSE, FALSE, TRUE},
137 * {"no files", "one file", "many files"}</pre>
138 *
139 * <p>Here is an example that shows formatting and parsing: </p>
140 *
141 * \code
142 * #include <unicode/choicfmt.h>
143 * #include <unicode/unistr.h>
144 * #include <iostream.h>
145 *
146 * int main(int argc, char *argv[]) {
147 * double limits[] = {1,2,3,4,5,6,7};
148 * UnicodeString monthNames[] = {
149 * "Sun","Mon","Tue","Wed","Thu","Fri","Sat"};
150 * ChoiceFormat fmt(limits, monthNames, 7);
151 * UnicodeString str;
152 * char buf[256];
153 * for (double x = 1.0; x <= 8.0; x += 1.0) {
154 * fmt.format(x, str);
155 * str.extract(0, str.length(), buf, 256, "");
156 * str.truncate(0);
157 * cout << x << " -> "
158 * << buf << endl;
159 * }
160 * cout << endl;
161 * return 0;
162 * }
163 * \endcode
164 *
165 * <p><em>User subclasses are not supported.</em> While clients may write
166 * subclasses, such code will not necessarily work and will not be
167 * guaranteed to work stably from release to release.
168 *
169 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
170 */
171 class U_I18N_API ChoiceFormat: public NumberFormat {
172 public:
173 /**
174 * Constructs a new ChoiceFormat from the pattern string.
175 *
176 * @param pattern Pattern used to construct object.
177 * @param status Output param to receive success code. If the
178 * pattern cannot be parsed, set to failure code.
179 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
180 */
181 ChoiceFormat(const UnicodeString& pattern,
182 UErrorCode& status);
185 /**
186 * Constructs a new ChoiceFormat with the given limits and message strings.
187 * All closure flags default to <code>FALSE</code>,
188 * equivalent to <code>less_than_or_equal</code> separators.
189 *
190 * Copies the limits and formats instead of adopting them.
191 *
192 * @param limits Array of limit values.
193 * @param formats Array of formats.
194 * @param count Size of 'limits' and 'formats' arrays.
195 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
196 */
197 ChoiceFormat(const double* limits,
198 const UnicodeString* formats,
199 int32_t count );
201 /**
202 * Constructs a new ChoiceFormat with the given limits, closure flags and message strings.
203 *
204 * Copies the limits and formats instead of adopting them.
205 *
206 * @param limits Array of limit values
207 * @param closures Array of booleans specifying whether each
208 * element of 'limits' is open or closed. If FALSE, then the
209 * corresponding limit number is a member of its range.
210 * If TRUE, then the limit number belongs to the previous range it.
211 * @param formats Array of formats
212 * @param count Size of 'limits', 'closures', and 'formats' arrays
213 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
214 */
215 ChoiceFormat(const double* limits,
216 const UBool* closures,
217 const UnicodeString* formats,
218 int32_t count);
220 /**
221 * Copy constructor.
222 *
223 * @param that ChoiceFormat object to be copied from
224 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
225 */
226 ChoiceFormat(const ChoiceFormat& that);
228 /**
229 * Assignment operator.
230 *
231 * @param that ChoiceFormat object to be copied
232 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
233 */
234 const ChoiceFormat& operator=(const ChoiceFormat& that);
236 /**
237 * Destructor.
238 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
239 */
240 virtual ~ChoiceFormat();
242 /**
243 * Clones this Format object. The caller owns the
244 * result and must delete it when done.
245 *
246 * @return a copy of this object
247 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
248 */
249 virtual Format* clone(void) const;
251 /**
252 * Returns true if the given Format objects are semantically equal.
253 * Objects of different subclasses are considered unequal.
254 *
255 * @param other ChoiceFormat object to be compared
256 * @return true if other is the same as this.
257 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
258 */
259 virtual UBool operator==(const Format& other) const;
261 /**
262 * Sets the pattern.
263 * @param pattern The pattern to be applied.
264 * @param status Output param set to success/failure code on
265 * exit. If the pattern is invalid, this will be
266 * set to a failure result.
267 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
268 */
269 virtual void applyPattern(const UnicodeString& pattern,
270 UErrorCode& status);
272 /**
273 * Sets the pattern.
274 * @param pattern The pattern to be applied.
275 * @param parseError Struct to receive information on position
276 * of error if an error is encountered
277 * @param status Output param set to success/failure code on
278 * exit. If the pattern is invalid, this will be
279 * set to a failure result.
280 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
281 */
282 virtual void applyPattern(const UnicodeString& pattern,
283 UParseError& parseError,
284 UErrorCode& status);
285 /**
286 * Gets the pattern.
287 *
288 * @param pattern Output param which will receive the pattern
289 * Previous contents are deleted.
290 * @return A reference to 'pattern'
291 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
292 */
293 virtual UnicodeString& toPattern(UnicodeString &pattern) const;
295 /**
296 * Sets the choices to be used in formatting.
297 * For details see the constructor with the same parameter list.
298 *
299 * @param limitsToCopy Contains the top value that you want
300 * parsed with that format,and should be in
301 * ascending sorted order. When formatting X,
302 * the choice will be the i, where limit[i]
303 * <= X < limit[i+1].
304 * @param formatsToCopy The format strings you want to use for each limit.
305 * @param count The size of the above arrays.
306 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
307 */
308 virtual void setChoices(const double* limitsToCopy,
309 const UnicodeString* formatsToCopy,
310 int32_t count );
312 /**
313 * Sets the choices to be used in formatting.
314 * For details see the constructor with the same parameter list.
315 *
316 * @param limits Array of limits
317 * @param closures Array of limit booleans
318 * @param formats Array of format string
319 * @param count The size of the above arrays
320 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
321 */
322 virtual void setChoices(const double* limits,
323 const UBool* closures,
324 const UnicodeString* formats,
325 int32_t count);
327 /**
328 * Returns NULL and 0.
329 * Before ICU 4.8, this used to return the choice limits array.
330 *
331 * @param count Will be set to 0.
332 * @return NULL
333 * @deprecated ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.
334 */
335 virtual const double* getLimits(int32_t& count) const;
337 /**
338 * Returns NULL and 0.
339 * Before ICU 4.8, this used to return the limit booleans array.
340 *
341 * @param count Will be set to 0.
342 * @return NULL
343 * @deprecated ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.
344 */
345 virtual const UBool* getClosures(int32_t& count) const;
347 /**
348 * Returns NULL and 0.
349 * Before ICU 4.8, this used to return the array of choice strings.
350 *
351 * @param count Will be set to 0.
352 * @return NULL
353 * @deprecated ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.
354 */
355 virtual const UnicodeString* getFormats(int32_t& count) const;
358 using NumberFormat::format;
360 /**
361 * Formats a double number using this object's choices.
362 *
363 * @param number The value to be formatted.
364 * @param appendTo Output parameter to receive result.
365 * Result is appended to existing contents.
366 * @param pos On input: an alignment field, if desired.
367 * On output: the offsets of the alignment field.
368 * @return Reference to 'appendTo' parameter.
369 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
370 */
371 virtual UnicodeString& format(double number,
372 UnicodeString& appendTo,
373 FieldPosition& pos) const;
374 /**
375 * Formats an int32_t number using this object's choices.
376 *
377 * @param number The value to be formatted.
378 * @param appendTo Output parameter to receive result.
379 * Result is appended to existing contents.
380 * @param pos On input: an alignment field, if desired.
381 * On output: the offsets of the alignment field.
382 * @return Reference to 'appendTo' parameter.
383 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
384 */
385 virtual UnicodeString& format(int32_t number,
386 UnicodeString& appendTo,
387 FieldPosition& pos) const;
389 /**
390 * Formats an int64_t number using this object's choices.
391 *
392 * @param number The value to be formatted.
393 * @param appendTo Output parameter to receive result.
394 * Result is appended to existing contents.
395 * @param pos On input: an alignment field, if desired.
396 * On output: the offsets of the alignment field.
397 * @return Reference to 'appendTo' parameter.
398 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
399 */
400 virtual UnicodeString& format(int64_t number,
401 UnicodeString& appendTo,
402 FieldPosition& pos) const;
404 /**
405 * Formats an array of objects using this object's choices.
406 *
407 * @param objs The array of objects to be formatted.
408 * @param cnt The size of objs.
409 * @param appendTo Output parameter to receive result.
410 * Result is appended to existing contents.
411 * @param pos On input: an alignment field, if desired.
412 * On output: the offsets of the alignment field.
413 * @param success Output param set to success/failure code on
414 * exit.
415 * @return Reference to 'appendTo' parameter.
416 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
417 */
418 virtual UnicodeString& format(const Formattable* objs,
419 int32_t cnt,
420 UnicodeString& appendTo,
421 FieldPosition& pos,
422 UErrorCode& success) const;
424 using NumberFormat::parse;
426 /**
427 * Looks for the longest match of any message string on the input text and,
428 * if there is a match, sets the result object to the corresponding range's number.
429 *
430 * If no string matches, then the parsePosition is unchanged.
431 *
432 * @param text The text to be parsed.
433 * @param result Formattable to be set to the parse result.
434 * If parse fails, return contents are undefined.
435 * @param parsePosition The position to start parsing at on input.
436 * On output, moved to after the last successfully
437 * parse character. On parse failure, does not change.
438 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
439 */
440 virtual void parse(const UnicodeString& text,
441 Formattable& result,
442 ParsePosition& parsePosition) const;
444 /**
445 * Returns a unique class ID POLYMORPHICALLY. Part of ICU's "poor man's RTTI".
446 *
447 * @return The class ID for this object. All objects of a
448 * given class have the same class ID. Objects of
449 * other classes have different class IDs.
450 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
451 */
452 virtual UClassID getDynamicClassID(void) const;
454 /**
455 * Returns the class ID for this class. This is useful only for
456 * comparing to a return value from getDynamicClassID(). For example:
457 * <pre>
458 * . Base* polymorphic_pointer = createPolymorphicObject();
459 * . if (polymorphic_pointer->getDynamicClassID() ==
460 * . Derived::getStaticClassID()) ...
461 * </pre>
462 * @return The class ID for all objects of this class.
463 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments.
464 */
465 static UClassID U_EXPORT2 getStaticClassID(void);
467 private:
468 /**
469 * Converts a double value to a string.
470 * @param value the double number to be converted.
471 * @param string the result string.
472 * @return the converted string.
473 */
474 static UnicodeString& dtos(double value, UnicodeString& string);
476 ChoiceFormat(); // default constructor not implemented
478 /**
479 * Construct a new ChoiceFormat with the limits and the corresponding formats
480 * based on the pattern.
481 *
482 * @param newPattern Pattern used to construct object.
483 * @param parseError Struct to receive information on position
484 * of error if an error is encountered.
485 * @param status Output param to receive success code. If the
486 * pattern cannot be parsed, set to failure code.
487 */
488 ChoiceFormat(const UnicodeString& newPattern,
489 UParseError& parseError,
490 UErrorCode& status);
492 friend class MessageFormat;
494 virtual void setChoices(const double* limits,
495 const UBool* closures,
496 const UnicodeString* formats,
497 int32_t count,
498 UErrorCode &errorCode);
500 /**
501 * Finds the ChoiceFormat sub-message for the given number.
502 * @param pattern A MessagePattern.
503 * @param partIndex the index of the first ChoiceFormat argument style part.
504 * @param number a number to be mapped to one of the ChoiceFormat argument's intervals
505 * @return the sub-message start part index.
506 */
507 static int32_t findSubMessage(const MessagePattern &pattern, int32_t partIndex, double number);
509 static double parseArgument(
510 const MessagePattern &pattern, int32_t partIndex,
511 const UnicodeString &source, ParsePosition &pos);
513 /**
514 * Matches the pattern string from the end of the partIndex to
515 * the beginning of the limitPartIndex,
516 * including all syntax except SKIP_SYNTAX,
517 * against the source string starting at sourceOffset.
518 * If they match, returns the length of the source string match.
519 * Otherwise returns -1.
520 */
521 static int32_t matchStringUntilLimitPart(
522 const MessagePattern &pattern, int32_t partIndex, int32_t limitPartIndex,
523 const UnicodeString &source, int32_t sourceOffset);
525 /**
526 * Some of the ChoiceFormat constructors do not have a UErrorCode paramater.
527 * We need _some_ way to provide one for the MessagePattern constructor.
528 * Alternatively, the MessagePattern could be a pointer field, but that is
529 * not nice either.
530 */
531 UErrorCode constructorErrorCode;
533 /**
534 * The MessagePattern which contains the parsed structure of the pattern string.
535 *
536 * Starting with ICU 4.8, the MessagePattern contains a sequence of
537 * numeric/selector/message parts corresponding to the parsed pattern.
538 * For details see the MessagePattern class API docs.
539 */
540 MessagePattern msgPattern;
542 /**
543 * Docs & fields from before ICU 4.8, before MessagePattern was used.
544 * Commented out, and left only for explanation of semantics.
545 * --------
546 * Each ChoiceFormat divides the range -Inf..+Inf into fCount
547 * intervals. The intervals are:
548 *
549 * 0: fChoiceLimits[0]..fChoiceLimits[1]
550 * 1: fChoiceLimits[1]..fChoiceLimits[2]
551 * ...
552 * fCount-2: fChoiceLimits[fCount-2]..fChoiceLimits[fCount-1]
553 * fCount-1: fChoiceLimits[fCount-1]..+Inf
554 *
555 * Interval 0 is special; during formatting (mapping numbers to
556 * strings), it also contains all numbers less than
557 * fChoiceLimits[0], as well as NaN values.
558 *
559 * Interval i maps to and from string fChoiceFormats[i]. When
560 * parsing (mapping strings to numbers), then intervals map to
561 * their lower limit, that is, interval i maps to fChoiceLimit[i].
562 *
563 * The intervals may be closed, half open, or open. This affects
564 * formatting but does not affect parsing. Interval i is affected
565 * by fClosures[i] and fClosures[i+1]. If fClosures[i]
566 * is FALSE, then the value fChoiceLimits[i] is in interval i.
567 * That is, intervals i and i are:
568 *
569 * i-1: ... x < fChoiceLimits[i]
570 * i: fChoiceLimits[i] <= x ...
571 *
572 * If fClosures[i] is TRUE, then the value fChoiceLimits[i] is
573 * in interval i-1. That is, intervals i-1 and i are:
574 *
575 * i-1: ... x <= fChoiceLimits[i]
576 * i: fChoiceLimits[i] < x ...
577 *
578 * Because of the nature of interval 0, fClosures[0] has no
579 * effect.
580 */
581 // double* fChoiceLimits;
582 // UBool* fClosures;
583 // UnicodeString* fChoiceFormats;
584 // int32_t fCount;
585 };
588 U_NAMESPACE_END
590 #endif // U_HIDE_DEPRECATED_API
591 #endif /* #if !UCONFIG_NO_FORMATTING */
593 #endif // CHOICFMT_H
594 //eof
