Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/msgfmt.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 * Copyright (C) 2007-2013, International Business Machines Corporation and
jpayne@69 5 * others. All Rights Reserved.
jpayne@69 6 ********************************************************************************
jpayne@69 7 *
jpayne@69 8 * File MSGFMT.H
jpayne@69 9 *
jpayne@69 10 * Modification History:
jpayne@69 11 *
jpayne@69 12 * Date Name Description
jpayne@69 13 * 02/19/97 aliu Converted from java.
jpayne@69 14 * 03/20/97 helena Finished first cut of implementation.
jpayne@69 15 * 07/22/98 stephen Removed operator!= (defined in Format)
jpayne@69 16 * 08/19/2002 srl Removing Javaisms
jpayne@69 17 *******************************************************************************/
jpayne@69 18
jpayne@69 19 #ifndef MSGFMT_H
jpayne@69 20 #define MSGFMT_H
jpayne@69 21
jpayne@69 22 #include "unicode/utypes.h"
jpayne@69 23
jpayne@69 24 #if U_SHOW_CPLUSPLUS_API
jpayne@69 25
jpayne@69 26 /**
jpayne@69 27 * \file
jpayne@69 28 * \brief C++ API: Formats messages in a language-neutral way.
jpayne@69 29 */
jpayne@69 30
jpayne@69 31 #if !UCONFIG_NO_FORMATTING
jpayne@69 32
jpayne@69 33 #include "unicode/format.h"
jpayne@69 34 #include "unicode/locid.h"
jpayne@69 35 #include "unicode/messagepattern.h"
jpayne@69 36 #include "unicode/parseerr.h"
jpayne@69 37 #include "unicode/plurfmt.h"
jpayne@69 38 #include "unicode/plurrule.h"
jpayne@69 39
jpayne@69 40 U_CDECL_BEGIN
jpayne@69 41 // Forward declaration.
jpayne@69 42 struct UHashtable;
jpayne@69 43 typedef struct UHashtable UHashtable; /**< @internal */
jpayne@69 44 U_CDECL_END
jpayne@69 45
jpayne@69 46 U_NAMESPACE_BEGIN
jpayne@69 47
jpayne@69 48 class AppendableWrapper;
jpayne@69 49 class DateFormat;
jpayne@69 50 class NumberFormat;
jpayne@69 51
jpayne@69 52 /**
jpayne@69 53 * <p>MessageFormat prepares strings for display to users,
jpayne@69 54 * with optional arguments (variables/placeholders).
jpayne@69 55 * The arguments can occur in any order, which is necessary for translation
jpayne@69 56 * into languages with different grammars.
jpayne@69 57 *
jpayne@69 58 * <p>A MessageFormat is constructed from a <em>pattern</em> string
jpayne@69 59 * with arguments in {curly braces} which will be replaced by formatted values.
jpayne@69 60 *
jpayne@69 61 * <p><code>MessageFormat</code> differs from the other <code>Format</code>
jpayne@69 62 * classes in that you create a <code>MessageFormat</code> object with one
jpayne@69 63 * of its constructors (not with a <code>createInstance</code> style factory
jpayne@69 64 * method). Factory methods aren't necessary because <code>MessageFormat</code>
jpayne@69 65 * itself doesn't implement locale-specific behavior. Any locale-specific
jpayne@69 66 * behavior is defined by the pattern that you provide and the
jpayne@69 67 * subformats used for inserted arguments.
jpayne@69 68 *
jpayne@69 69 * <p>Arguments can be named (using identifiers) or numbered (using small ASCII-digit integers).
jpayne@69 70 * Some of the API methods work only with argument numbers and throw an exception
jpayne@69 71 * if the pattern has named arguments (see {@link #usesNamedArguments()}).
jpayne@69 72 *
jpayne@69 73 * <p>An argument might not specify any format type. In this case,
jpayne@69 74 * a numeric value is formatted with a default (for the locale) NumberFormat,
jpayne@69 75 * and a date/time value is formatted with a default (for the locale) DateFormat.
jpayne@69 76 *
jpayne@69 77 * <p>An argument might specify a "simple" type for which the specified
jpayne@69 78 * Format object is created, cached and used.
jpayne@69 79 *
jpayne@69 80 * <p>An argument might have a "complex" type with nested MessageFormat sub-patterns.
jpayne@69 81 * During formatting, one of these sub-messages is selected according to the argument value
jpayne@69 82 * and recursively formatted.
jpayne@69 83 *
jpayne@69 84 * <p>After construction, a custom Format object can be set for
jpayne@69 85 * a top-level argument, overriding the default formatting and parsing behavior
jpayne@69 86 * for that argument.
jpayne@69 87 * However, custom formatting can be achieved more simply by writing
jpayne@69 88 * a typeless argument in the pattern string
jpayne@69 89 * and supplying it with a preformatted string value.
jpayne@69 90 *
jpayne@69 91 * <p>When formatting, MessageFormat takes a collection of argument values
jpayne@69 92 * and writes an output string.
jpayne@69 93 * The argument values may be passed as an array
jpayne@69 94 * (when the pattern contains only numbered arguments)
jpayne@69 95 * or as an array of names and and an array of arguments (which works for both named
jpayne@69 96 * and numbered arguments).
jpayne@69 97 *
jpayne@69 98 * <p>Each argument is matched with one of the input values by array index or argument name
jpayne@69 99 * and formatted according to its pattern specification
jpayne@69 100 * (or using a custom Format object if one was set).
jpayne@69 101 * A numbered pattern argument is matched with an argument name that contains that number
jpayne@69 102 * as an ASCII-decimal-digit string (without leading zero).
jpayne@69 103 *
jpayne@69 104 * <h4><a name="patterns">Patterns and Their Interpretation</a></h4>
jpayne@69 105 *
jpayne@69 106 * <code>MessageFormat</code> uses patterns of the following form:
jpayne@69 107 * <pre>
jpayne@69 108 * message = messageText (argument messageText)*
jpayne@69 109 * argument = noneArg | simpleArg | complexArg
jpayne@69 110 * complexArg = choiceArg | pluralArg | selectArg | selectordinalArg
jpayne@69 111 *
jpayne@69 112 * noneArg = '{' argNameOrNumber '}'
jpayne@69 113 * simpleArg = '{' argNameOrNumber ',' argType [',' argStyle] '}'
jpayne@69 114 * choiceArg = '{' argNameOrNumber ',' "choice" ',' choiceStyle '}'
jpayne@69 115 * pluralArg = '{' argNameOrNumber ',' "plural" ',' pluralStyle '}'
jpayne@69 116 * selectArg = '{' argNameOrNumber ',' "select" ',' selectStyle '}'
jpayne@69 117 * selectordinalArg = '{' argNameOrNumber ',' "selectordinal" ',' pluralStyle '}'
jpayne@69 118 *
jpayne@69 119 * choiceStyle: see {@link ChoiceFormat}
jpayne@69 120 * pluralStyle: see {@link PluralFormat}
jpayne@69 121 * selectStyle: see {@link SelectFormat}
jpayne@69 122 *
jpayne@69 123 * argNameOrNumber = argName | argNumber
jpayne@69 124 * argName = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+
jpayne@69 125 * argNumber = '0' | ('1'..'9' ('0'..'9')*)
jpayne@69 126 *
jpayne@69 127 * argType = "number" | "date" | "time" | "spellout" | "ordinal" | "duration"
jpayne@69 128 * argStyle = "short" | "medium" | "long" | "full" | "integer" | "currency" | "percent" | argStyleText | "::" argSkeletonText
jpayne@69 129 * </pre>
jpayne@69 130 *
jpayne@69 131 * <ul>
jpayne@69 132 * <li>messageText can contain quoted literal strings including syntax characters.
jpayne@69 133 * A quoted literal string begins with an ASCII apostrophe and a syntax character
jpayne@69 134 * (usually a {curly brace}) and continues until the next single apostrophe.
jpayne@69 135 * A double ASCII apostrohpe inside or outside of a quoted string represents
jpayne@69 136 * one literal apostrophe.
jpayne@69 137 * <li>Quotable syntax characters are the {curly braces} in all messageText parts,
jpayne@69 138 * plus the '#' sign in a messageText immediately inside a pluralStyle,
jpayne@69 139 * and the '|' symbol in a messageText immediately inside a choiceStyle.
jpayne@69 140 * <li>See also {@link #UMessagePatternApostropheMode}
jpayne@69 141 * <li>In argStyleText, every single ASCII apostrophe begins and ends quoted literal text,
jpayne@69 142 * and unquoted {curly braces} must occur in matched pairs.
jpayne@69 143 * </ul>
jpayne@69 144 *
jpayne@69 145 * <p>Recommendation: Use the real apostrophe (single quote) character
jpayne@69 146 * \htmlonly&#x2019;\endhtmlonly (U+2019) for
jpayne@69 147 * human-readable text, and use the ASCII apostrophe ' (U+0027)
jpayne@69 148 * only in program syntax, like quoting in MessageFormat.
jpayne@69 149 * See the annotations for U+0027 Apostrophe in The Unicode Standard.
jpayne@69 150 *
jpayne@69 151 * <p>The <code>choice</code> argument type is deprecated.
jpayne@69 152 * Use <code>plural</code> arguments for proper plural selection,
jpayne@69 153 * and <code>select</code> arguments for simple selection among a fixed set of choices.
jpayne@69 154 *
jpayne@69 155 * <p>The <code>argType</code> and <code>argStyle</code> values are used to create
jpayne@69 156 * a <code>Format</code> instance for the format element. The following
jpayne@69 157 * table shows how the values map to Format instances. Combinations not
jpayne@69 158 * shown in the table are illegal. Any <code>argStyleText</code> must
jpayne@69 159 * be a valid pattern string for the Format subclass used.
jpayne@69 160 *
jpayne@69 161 * <p><table border=1>
jpayne@69 162 * <tr>
jpayne@69 163 * <th>argType
jpayne@69 164 * <th>argStyle
jpayne@69 165 * <th>resulting Format object
jpayne@69 166 * <tr>
jpayne@69 167 * <td colspan=2><i>(none)</i>
jpayne@69 168 * <td><code>null</code>
jpayne@69 169 * <tr>
jpayne@69 170 * <td rowspan=6><code>number</code>
jpayne@69 171 * <td><i>(none)</i>
jpayne@69 172 * <td><code>NumberFormat.createInstance(getLocale(), status)</code>
jpayne@69 173 * <tr>
jpayne@69 174 * <td><code>integer</code>
jpayne@69 175 * <td><code>NumberFormat.createInstance(getLocale(), kNumberStyle, status)</code>
jpayne@69 176 * <tr>
jpayne@69 177 * <td><code>currency</code>
jpayne@69 178 * <td><code>NumberFormat.createCurrencyInstance(getLocale(), status)</code>
jpayne@69 179 * <tr>
jpayne@69 180 * <td><code>percent</code>
jpayne@69 181 * <td><code>NumberFormat.createPercentInstance(getLocale(), status)</code>
jpayne@69 182 * <tr>
jpayne@69 183 * <td><i>argStyleText</i>
jpayne@69 184 * <td><code>new DecimalFormat(argStyleText, new DecimalFormatSymbols(getLocale(), status), status)</code>
jpayne@69 185 * <tr>
jpayne@69 186 * <td><i>argSkeletonText</i>
jpayne@69 187 * <td><code>NumberFormatter::forSkeleton(argSkeletonText, status).locale(getLocale()).toFormat(status)</code>
jpayne@69 188 * <tr>
jpayne@69 189 * <td rowspan=7><code>date</code>
jpayne@69 190 * <td><i>(none)</i>
jpayne@69 191 * <td><code>DateFormat.createDateInstance(kDefault, getLocale(), status)</code>
jpayne@69 192 * <tr>
jpayne@69 193 * <td><code>short</code>
jpayne@69 194 * <td><code>DateFormat.createDateInstance(kShort, getLocale(), status)</code>
jpayne@69 195 * <tr>
jpayne@69 196 * <td><code>medium</code>
jpayne@69 197 * <td><code>DateFormat.createDateInstance(kDefault, getLocale(), status)</code>
jpayne@69 198 * <tr>
jpayne@69 199 * <td><code>long</code>
jpayne@69 200 * <td><code>DateFormat.createDateInstance(kLong, getLocale(), status)</code>
jpayne@69 201 * <tr>
jpayne@69 202 * <td><code>full</code>
jpayne@69 203 * <td><code>DateFormat.createDateInstance(kFull, getLocale(), status)</code>
jpayne@69 204 * <tr>
jpayne@69 205 * <td><i>argStyleText</i>
jpayne@69 206 * <td><code>new SimpleDateFormat(argStyleText, getLocale(), status)</code>
jpayne@69 207 * <tr>
jpayne@69 208 * <td><i>argSkeletonText</i>
jpayne@69 209 * <td><code>DateFormat::createInstanceForSkeleton(argSkeletonText, getLocale(), status)</code>
jpayne@69 210 * <tr>
jpayne@69 211 * <td rowspan=6><code>time</code>
jpayne@69 212 * <td><i>(none)</i>
jpayne@69 213 * <td><code>DateFormat.createTimeInstance(kDefault, getLocale(), status)</code>
jpayne@69 214 * <tr>
jpayne@69 215 * <td><code>short</code>
jpayne@69 216 * <td><code>DateFormat.createTimeInstance(kShort, getLocale(), status)</code>
jpayne@69 217 * <tr>
jpayne@69 218 * <td><code>medium</code>
jpayne@69 219 * <td><code>DateFormat.createTimeInstance(kDefault, getLocale(), status)</code>
jpayne@69 220 * <tr>
jpayne@69 221 * <td><code>long</code>
jpayne@69 222 * <td><code>DateFormat.createTimeInstance(kLong, getLocale(), status)</code>
jpayne@69 223 * <tr>
jpayne@69 224 * <td><code>full</code>
jpayne@69 225 * <td><code>DateFormat.createTimeInstance(kFull, getLocale(), status)</code>
jpayne@69 226 * <tr>
jpayne@69 227 * <td><i>argStyleText</i>
jpayne@69 228 * <td><code>new SimpleDateFormat(argStyleText, getLocale(), status)</code>
jpayne@69 229 * <tr>
jpayne@69 230 * <td><code>spellout</code>
jpayne@69 231 * <td><i>argStyleText (optional)</i>
jpayne@69 232 * <td><code>new RuleBasedNumberFormat(URBNF_SPELLOUT, getLocale(), status)
jpayne@69 233 * <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText, status);</code>
jpayne@69 234 * <tr>
jpayne@69 235 * <td><code>ordinal</code>
jpayne@69 236 * <td><i>argStyleText (optional)</i>
jpayne@69 237 * <td><code>new RuleBasedNumberFormat(URBNF_ORDINAL, getLocale(), status)
jpayne@69 238 * <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText, status);</code>
jpayne@69 239 * <tr>
jpayne@69 240 * <td><code>duration</code>
jpayne@69 241 * <td><i>argStyleText (optional)</i>
jpayne@69 242 * <td><code>new RuleBasedNumberFormat(URBNF_DURATION, getLocale(), status)
jpayne@69 243 * <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText, status);</code>
jpayne@69 244 * </table>
jpayne@69 245 * <p>
jpayne@69 246 *
jpayne@69 247 * <h4>Argument formatting</h4>
jpayne@69 248 *
jpayne@69 249 * <p>Arguments are formatted according to their type, using the default
jpayne@69 250 * ICU formatters for those types, unless otherwise specified.</p>
jpayne@69 251 *
jpayne@69 252 * <p>There are also several ways to control the formatting.</p>
jpayne@69 253 *
jpayne@69 254 * <p>We recommend you use default styles, predefined style values, skeletons,
jpayne@69 255 * or preformatted values, but not pattern strings or custom format objects.</p>
jpayne@69 256 *
jpayne@69 257 * <p>For more details, see the
jpayne@69 258 * <a href="http://userguide.icu-project.org/formatparse/messages">ICU User Guide</a>.</p>
jpayne@69 259 *
jpayne@69 260 * <h4>Usage Information</h4>
jpayne@69 261 *
jpayne@69 262 * <p>Here are some examples of usage:
jpayne@69 263 * Example 1:
jpayne@69 264 *
jpayne@69 265 * <pre>
jpayne@69 266 * \code
jpayne@69 267 * UErrorCode success = U_ZERO_ERROR;
jpayne@69 268 * GregorianCalendar cal(success);
jpayne@69 269 * Formattable arguments[] = {
jpayne@69 270 * 7L,
jpayne@69 271 * Formattable( (Date) cal.getTime(success), Formattable::kIsDate),
jpayne@69 272 * "a disturbance in the Force"
jpayne@69 273 * };
jpayne@69 274 *
jpayne@69 275 * UnicodeString result;
jpayne@69 276 * MessageFormat::format(
jpayne@69 277 * "At {1,time,::jmm} on {1,date,::dMMMM}, there was {2} on planet {0,number}.",
jpayne@69 278 * arguments, 3, result, success );
jpayne@69 279 *
jpayne@69 280 * cout << "result: " << result << endl;
jpayne@69 281 * //<output>: At 4:34 PM on March 23, there was a disturbance
jpayne@69 282 * // in the Force on planet 7.
jpayne@69 283 * \endcode
jpayne@69 284 * </pre>
jpayne@69 285 *
jpayne@69 286 * Typically, the message format will come from resources, and the
jpayne@69 287 * arguments will be dynamically set at runtime.
jpayne@69 288 *
jpayne@69 289 * <p>Example 2:
jpayne@69 290 *
jpayne@69 291 * <pre>
jpayne@69 292 * \code
jpayne@69 293 * success = U_ZERO_ERROR;
jpayne@69 294 * Formattable testArgs[] = {3L, "MyDisk"};
jpayne@69 295 *
jpayne@69 296 * MessageFormat form(
jpayne@69 297 * "The disk \"{1}\" contains {0} file(s).", success );
jpayne@69 298 *
jpayne@69 299 * UnicodeString string;
jpayne@69 300 * FieldPosition fpos = 0;
jpayne@69 301 * cout << "format: " << form.format(testArgs, 2, string, fpos, success ) << endl;
jpayne@69 302 *
jpayne@69 303 * // output, with different testArgs:
jpayne@69 304 * // output: The disk "MyDisk" contains 0 file(s).
jpayne@69 305 * // output: The disk "MyDisk" contains 1 file(s).
jpayne@69 306 * // output: The disk "MyDisk" contains 1,273 file(s).
jpayne@69 307 * \endcode
jpayne@69 308 * </pre>
jpayne@69 309 *
jpayne@69 310 *
jpayne@69 311 * <p>For messages that include plural forms, you can use a plural argument:
jpayne@69 312 * <pre>
jpayne@69 313 * \code
jpayne@69 314 * success = U_ZERO_ERROR;
jpayne@69 315 * MessageFormat msgFmt(
jpayne@69 316 * "{num_files, plural, "
jpayne@69 317 * "=0{There are no files on disk \"{disk_name}\".}"
jpayne@69 318 * "=1{There is one file on disk \"{disk_name}\".}"
jpayne@69 319 * "other{There are # files on disk \"{disk_name}\".}}",
jpayne@69 320 * Locale("en"),
jpayne@69 321 * success);
jpayne@69 322 * FieldPosition fpos = 0;
jpayne@69 323 * Formattable testArgs[] = {0L, "MyDisk"};
jpayne@69 324 * UnicodeString testArgsNames[] = {"num_files", "disk_name"};
jpayne@69 325 * UnicodeString result;
jpayne@69 326 * cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);
jpayne@69 327 * testArgs[0] = 3L;
jpayne@69 328 * cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);
jpayne@69 329 * \endcode
jpayne@69 330 * <em>output</em>:
jpayne@69 331 * There are no files on disk "MyDisk".
jpayne@69 332 * There are 3 files on "MyDisk".
jpayne@69 333 * </pre>
jpayne@69 334 * See {@link PluralFormat} and {@link PluralRules} for details.
jpayne@69 335 *
jpayne@69 336 * <h4><a name="synchronization">Synchronization</a></h4>
jpayne@69 337 *
jpayne@69 338 * <p>MessageFormats are not synchronized.
jpayne@69 339 * It is recommended to create separate format instances for each thread.
jpayne@69 340 * If multiple threads access a format concurrently, it must be synchronized
jpayne@69 341 * externally.
jpayne@69 342 *
jpayne@69 343 * @stable ICU 2.0
jpayne@69 344 */
jpayne@69 345 class U_I18N_API MessageFormat : public Format {
jpayne@69 346 public:
jpayne@69 347 #ifndef U_HIDE_OBSOLETE_API
jpayne@69 348 /**
jpayne@69 349 * Enum type for kMaxFormat.
jpayne@69 350 * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6,
jpayne@69 351 * rendering this enum type obsolete.
jpayne@69 352 */
jpayne@69 353 enum EFormatNumber {
jpayne@69 354 /**
jpayne@69 355 * The maximum number of arguments.
jpayne@69 356 * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6,
jpayne@69 357 * rendering this constant obsolete.
jpayne@69 358 */
jpayne@69 359 kMaxFormat = 10
jpayne@69 360 };
jpayne@69 361 #endif /* U_HIDE_OBSOLETE_API */
jpayne@69 362
jpayne@69 363 /**
jpayne@69 364 * Constructs a new MessageFormat using the given pattern and the
jpayne@69 365 * default locale.
jpayne@69 366 *
jpayne@69 367 * @param pattern Pattern used to construct object.
jpayne@69 368 * @param status Input/output error code. If the
jpayne@69 369 * pattern cannot be parsed, set to failure code.
jpayne@69 370 * @stable ICU 2.0
jpayne@69 371 */
jpayne@69 372 MessageFormat(const UnicodeString& pattern,
jpayne@69 373 UErrorCode &status);
jpayne@69 374
jpayne@69 375 /**
jpayne@69 376 * Constructs a new MessageFormat using the given pattern and locale.
jpayne@69 377 * @param pattern Pattern used to construct object.
jpayne@69 378 * @param newLocale The locale to use for formatting dates and numbers.
jpayne@69 379 * @param status Input/output error code. If the
jpayne@69 380 * pattern cannot be parsed, set to failure code.
jpayne@69 381 * @stable ICU 2.0
jpayne@69 382 */
jpayne@69 383 MessageFormat(const UnicodeString& pattern,
jpayne@69 384 const Locale& newLocale,
jpayne@69 385 UErrorCode& status);
jpayne@69 386 /**
jpayne@69 387 * Constructs a new MessageFormat using the given pattern and locale.
jpayne@69 388 * @param pattern Pattern used to construct object.
jpayne@69 389 * @param newLocale The locale to use for formatting dates and numbers.
jpayne@69 390 * @param parseError Struct to receive information on the position
jpayne@69 391 * of an error within the pattern.
jpayne@69 392 * @param status Input/output error code. If the
jpayne@69 393 * pattern cannot be parsed, set to failure code.
jpayne@69 394 * @stable ICU 2.0
jpayne@69 395 */
jpayne@69 396 MessageFormat(const UnicodeString& pattern,
jpayne@69 397 const Locale& newLocale,
jpayne@69 398 UParseError& parseError,
jpayne@69 399 UErrorCode& status);
jpayne@69 400 /**
jpayne@69 401 * Constructs a new MessageFormat from an existing one.
jpayne@69 402 * @stable ICU 2.0
jpayne@69 403 */
jpayne@69 404 MessageFormat(const MessageFormat&);
jpayne@69 405
jpayne@69 406 /**
jpayne@69 407 * Assignment operator.
jpayne@69 408 * @stable ICU 2.0
jpayne@69 409 */
jpayne@69 410 const MessageFormat& operator=(const MessageFormat&);
jpayne@69 411
jpayne@69 412 /**
jpayne@69 413 * Destructor.
jpayne@69 414 * @stable ICU 2.0
jpayne@69 415 */
jpayne@69 416 virtual ~MessageFormat();
jpayne@69 417
jpayne@69 418 /**
jpayne@69 419 * Clones this Format object polymorphically. The caller owns the
jpayne@69 420 * result and should delete it when done.
jpayne@69 421 * @stable ICU 2.0
jpayne@69 422 */
jpayne@69 423 virtual MessageFormat* clone() const;
jpayne@69 424
jpayne@69 425 /**
jpayne@69 426 * Returns true if the given Format objects are semantically equal.
jpayne@69 427 * Objects of different subclasses are considered unequal.
jpayne@69 428 * @param other the object to be compared with.
jpayne@69 429 * @return true if the given Format objects are semantically equal.
jpayne@69 430 * @stable ICU 2.0
jpayne@69 431 */
jpayne@69 432 virtual UBool operator==(const Format& other) const;
jpayne@69 433
jpayne@69 434 /**
jpayne@69 435 * Sets the locale to be used for creating argument Format objects.
jpayne@69 436 * @param theLocale the new locale value to be set.
jpayne@69 437 * @stable ICU 2.0
jpayne@69 438 */
jpayne@69 439 virtual void setLocale(const Locale& theLocale);
jpayne@69 440
jpayne@69 441 /**
jpayne@69 442 * Gets the locale used for creating argument Format objects.
jpayne@69 443 * format information.
jpayne@69 444 * @return the locale of the object.
jpayne@69 445 * @stable ICU 2.0
jpayne@69 446 */
jpayne@69 447 virtual const Locale& getLocale(void) const;
jpayne@69 448
jpayne@69 449 /**
jpayne@69 450 * Applies the given pattern string to this message format.
jpayne@69 451 *
jpayne@69 452 * @param pattern The pattern to be applied.
jpayne@69 453 * @param status Input/output error code. If the
jpayne@69 454 * pattern cannot be parsed, set to failure code.
jpayne@69 455 * @stable ICU 2.0
jpayne@69 456 */
jpayne@69 457 virtual void applyPattern(const UnicodeString& pattern,
jpayne@69 458 UErrorCode& status);
jpayne@69 459 /**
jpayne@69 460 * Applies the given pattern string to this message format.
jpayne@69 461 *
jpayne@69 462 * @param pattern The pattern to be applied.
jpayne@69 463 * @param parseError Struct to receive information on the position
jpayne@69 464 * of an error within the pattern.
jpayne@69 465 * @param status Input/output error code. If the
jpayne@69 466 * pattern cannot be parsed, set to failure code.
jpayne@69 467 * @stable ICU 2.0
jpayne@69 468 */
jpayne@69 469 virtual void applyPattern(const UnicodeString& pattern,
jpayne@69 470 UParseError& parseError,
jpayne@69 471 UErrorCode& status);
jpayne@69 472
jpayne@69 473 /**
jpayne@69 474 * Sets the UMessagePatternApostropheMode and the pattern used by this message format.
jpayne@69 475 * Parses the pattern and caches Format objects for simple argument types.
jpayne@69 476 * Patterns and their interpretation are specified in the
jpayne@69 477 * <a href="#patterns">class description</a>.
jpayne@69 478 * <p>
jpayne@69 479 * This method is best used only once on a given object to avoid confusion about the mode,
jpayne@69 480 * and after constructing the object with an empty pattern string to minimize overhead.
jpayne@69 481 *
jpayne@69 482 * @param pattern The pattern to be applied.
jpayne@69 483 * @param aposMode The new apostrophe mode.
jpayne@69 484 * @param parseError Struct to receive information on the position
jpayne@69 485 * of an error within the pattern.
jpayne@69 486 * Can be NULL.
jpayne@69 487 * @param status Input/output error code. If the
jpayne@69 488 * pattern cannot be parsed, set to failure code.
jpayne@69 489 * @stable ICU 4.8
jpayne@69 490 */
jpayne@69 491 virtual void applyPattern(const UnicodeString& pattern,
jpayne@69 492 UMessagePatternApostropheMode aposMode,
jpayne@69 493 UParseError* parseError,
jpayne@69 494 UErrorCode& status);
jpayne@69 495
jpayne@69 496 /**
jpayne@69 497 * @return this instance's UMessagePatternApostropheMode.
jpayne@69 498 * @stable ICU 4.8
jpayne@69 499 */
jpayne@69 500 UMessagePatternApostropheMode getApostropheMode() const {
jpayne@69 501 return msgPattern.getApostropheMode();
jpayne@69 502 }
jpayne@69 503
jpayne@69 504 /**
jpayne@69 505 * Returns a pattern that can be used to recreate this object.
jpayne@69 506 *
jpayne@69 507 * @param appendTo Output parameter to receive the pattern.
jpayne@69 508 * Result is appended to existing contents.
jpayne@69 509 * @return Reference to 'appendTo' parameter.
jpayne@69 510 * @stable ICU 2.0
jpayne@69 511 */
jpayne@69 512 virtual UnicodeString& toPattern(UnicodeString& appendTo) const;
jpayne@69 513
jpayne@69 514 /**
jpayne@69 515 * Sets subformats.
jpayne@69 516 * See the class description about format numbering.
jpayne@69 517 * The caller should not delete the Format objects after this call.
jpayne@69 518 * <EM>The array formatsToAdopt is not itself adopted.</EM> Its
jpayne@69 519 * ownership is retained by the caller. If the call fails because
jpayne@69 520 * memory cannot be allocated, then the formats will be deleted
jpayne@69 521 * by this method, and this object will remain unchanged.
jpayne@69 522 *
jpayne@69 523 * <p>If this format uses named arguments, the new formats are discarded
jpayne@69 524 * and this format remains unchanged.
jpayne@69 525 *
jpayne@69 526 * @stable ICU 2.0
jpayne@69 527 * @param formatsToAdopt the format to be adopted.
jpayne@69 528 * @param count the size of the array.
jpayne@69 529 */
jpayne@69 530 virtual void adoptFormats(Format** formatsToAdopt, int32_t count);
jpayne@69 531
jpayne@69 532 /**
jpayne@69 533 * Sets subformats.
jpayne@69 534 * See the class description about format numbering.
jpayne@69 535 * Each item in the array is cloned into the internal array.
jpayne@69 536 * If the call fails because memory cannot be allocated, then this
jpayne@69 537 * object will remain unchanged.
jpayne@69 538 *
jpayne@69 539 * <p>If this format uses named arguments, the new formats are discarded
jpayne@69 540 * and this format remains unchanged.
jpayne@69 541 *
jpayne@69 542 * @stable ICU 2.0
jpayne@69 543 * @param newFormats the new format to be set.
jpayne@69 544 * @param cnt the size of the array.
jpayne@69 545 */
jpayne@69 546 virtual void setFormats(const Format** newFormats, int32_t cnt);
jpayne@69 547
jpayne@69 548
jpayne@69 549 /**
jpayne@69 550 * Sets one subformat.
jpayne@69 551 * See the class description about format numbering.
jpayne@69 552 * The caller should not delete the Format object after this call.
jpayne@69 553 * If the number is over the number of formats already set,
jpayne@69 554 * the item will be deleted and ignored.
jpayne@69 555 *
jpayne@69 556 * <p>If this format uses named arguments, the new format is discarded
jpayne@69 557 * and this format remains unchanged.
jpayne@69 558 *
jpayne@69 559 * @stable ICU 2.0
jpayne@69 560 * @param formatNumber index of the subformat.
jpayne@69 561 * @param formatToAdopt the format to be adopted.
jpayne@69 562 */
jpayne@69 563 virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt);
jpayne@69 564
jpayne@69 565 /**
jpayne@69 566 * Sets one subformat.
jpayne@69 567 * See the class description about format numbering.
jpayne@69 568 * If the number is over the number of formats already set,
jpayne@69 569 * the item will be ignored.
jpayne@69 570 * @param formatNumber index of the subformat.
jpayne@69 571 * @param format the format to be set.
jpayne@69 572 * @stable ICU 2.0
jpayne@69 573 */
jpayne@69 574 virtual void setFormat(int32_t formatNumber, const Format& format);
jpayne@69 575
jpayne@69 576 /**
jpayne@69 577 * Gets format names. This function returns formatNames in StringEnumerations
jpayne@69 578 * which can be used with getFormat() and setFormat() to export formattable
jpayne@69 579 * array from current MessageFormat to another. It is the caller's responsibility
jpayne@69 580 * to delete the returned formatNames.
jpayne@69 581 * @param status output param set to success/failure code.
jpayne@69 582 * @stable ICU 4.0
jpayne@69 583 */
jpayne@69 584 virtual StringEnumeration* getFormatNames(UErrorCode& status);
jpayne@69 585
jpayne@69 586 /**
jpayne@69 587 * Gets subformat pointer for given format name.
jpayne@69 588 * This function supports both named and numbered
jpayne@69 589 * arguments. If numbered, the formatName is the
jpayne@69 590 * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
jpayne@69 591 * The returned Format object should not be deleted by the caller,
jpayne@69 592 * nor should the ponter of other object . The pointer and its
jpayne@69 593 * contents remain valid only until the next call to any method
jpayne@69 594 * of this class is made with this object.
jpayne@69 595 * @param formatName the name or number specifying a format
jpayne@69 596 * @param status output param set to success/failure code.
jpayne@69 597 * @stable ICU 4.0
jpayne@69 598 */
jpayne@69 599 virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status);
jpayne@69 600
jpayne@69 601 /**
jpayne@69 602 * Sets one subformat for given format name.
jpayne@69 603 * See the class description about format name.
jpayne@69 604 * This function supports both named and numbered
jpayne@69 605 * arguments-- if numbered, the formatName is the
jpayne@69 606 * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
jpayne@69 607 * If there is no matched formatName or wrong type,
jpayne@69 608 * the item will be ignored.
jpayne@69 609 * @param formatName Name of the subformat.
jpayne@69 610 * @param format the format to be set.
jpayne@69 611 * @param status output param set to success/failure code.
jpayne@69 612 * @stable ICU 4.0
jpayne@69 613 */
jpayne@69 614 virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status);
jpayne@69 615
jpayne@69 616 /**
jpayne@69 617 * Sets one subformat for given format name.
jpayne@69 618 * See the class description about format name.
jpayne@69 619 * This function supports both named and numbered
jpayne@69 620 * arguments-- if numbered, the formatName is the
jpayne@69 621 * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
jpayne@69 622 * If there is no matched formatName or wrong type,
jpayne@69 623 * the item will be ignored.
jpayne@69 624 * The caller should not delete the Format object after this call.
jpayne@69 625 * @param formatName Name of the subformat.
jpayne@69 626 * @param formatToAdopt Format to be adopted.
jpayne@69 627 * @param status output param set to success/failure code.
jpayne@69 628 * @stable ICU 4.0
jpayne@69 629 */
jpayne@69 630 virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status);
jpayne@69 631
jpayne@69 632 /**
jpayne@69 633 * Gets an array of subformats of this object. The returned array
jpayne@69 634 * should not be deleted by the caller, nor should the pointers
jpayne@69 635 * within the array. The array and its contents remain valid only
jpayne@69 636 * until the next call to this format. See the class description
jpayne@69 637 * about format numbering.
jpayne@69 638 *
jpayne@69 639 * @param count output parameter to receive the size of the array
jpayne@69 640 * @return an array of count Format* objects, or NULL if out of
jpayne@69 641 * memory. Any or all of the array elements may be NULL.
jpayne@69 642 * @stable ICU 2.0
jpayne@69 643 */
jpayne@69 644 virtual const Format** getFormats(int32_t& count) const;
jpayne@69 645
jpayne@69 646
jpayne@69 647 using Format::format;
jpayne@69 648
jpayne@69 649 /**
jpayne@69 650 * Formats the given array of arguments into a user-readable string.
jpayne@69 651 * Does not take ownership of the Formattable* array or its contents.
jpayne@69 652 *
jpayne@69 653 * <p>If this format uses named arguments, appendTo is unchanged and
jpayne@69 654 * status is set to U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69 655 *
jpayne@69 656 * @param source An array of objects to be formatted.
jpayne@69 657 * @param count The number of elements of 'source'.
jpayne@69 658 * @param appendTo Output parameter to receive result.
jpayne@69 659 * Result is appended to existing contents.
jpayne@69 660 * @param ignore Not used; inherited from base class API.
jpayne@69 661 * @param status Input/output error code. If the
jpayne@69 662 * pattern cannot be parsed, set to failure code.
jpayne@69 663 * @return Reference to 'appendTo' parameter.
jpayne@69 664 * @stable ICU 2.0
jpayne@69 665 */
jpayne@69 666 UnicodeString& format(const Formattable* source,
jpayne@69 667 int32_t count,
jpayne@69 668 UnicodeString& appendTo,
jpayne@69 669 FieldPosition& ignore,
jpayne@69 670 UErrorCode& status) const;
jpayne@69 671
jpayne@69 672 /**
jpayne@69 673 * Formats the given array of arguments into a user-readable string
jpayne@69 674 * using the given pattern.
jpayne@69 675 *
jpayne@69 676 * <p>If this format uses named arguments, appendTo is unchanged and
jpayne@69 677 * status is set to U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69 678 *
jpayne@69 679 * @param pattern The pattern.
jpayne@69 680 * @param arguments An array of objects to be formatted.
jpayne@69 681 * @param count The number of elements of 'source'.
jpayne@69 682 * @param appendTo Output parameter to receive result.
jpayne@69 683 * Result is appended to existing contents.
jpayne@69 684 * @param status Input/output error code. If the
jpayne@69 685 * pattern cannot be parsed, set to failure code.
jpayne@69 686 * @return Reference to 'appendTo' parameter.
jpayne@69 687 * @stable ICU 2.0
jpayne@69 688 */
jpayne@69 689 static UnicodeString& format(const UnicodeString& pattern,
jpayne@69 690 const Formattable* arguments,
jpayne@69 691 int32_t count,
jpayne@69 692 UnicodeString& appendTo,
jpayne@69 693 UErrorCode& status);
jpayne@69 694
jpayne@69 695 /**
jpayne@69 696 * Formats the given array of arguments into a user-readable
jpayne@69 697 * string. The array must be stored within a single Formattable
jpayne@69 698 * object of type kArray. If the Formattable object type is not of
jpayne@69 699 * type kArray, then returns a failing UErrorCode.
jpayne@69 700 *
jpayne@69 701 * <p>If this format uses named arguments, appendTo is unchanged and
jpayne@69 702 * status is set to U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69 703 *
jpayne@69 704 * @param obj A Formattable of type kArray containing
jpayne@69 705 * arguments to be formatted.
jpayne@69 706 * @param appendTo Output parameter to receive result.
jpayne@69 707 * Result is appended to existing contents.
jpayne@69 708 * @param pos On input: an alignment field, if desired.
jpayne@69 709 * On output: the offsets of the alignment field.
jpayne@69 710 * @param status Input/output error code. If the
jpayne@69 711 * pattern cannot be parsed, set to failure code.
jpayne@69 712 * @return Reference to 'appendTo' parameter.
jpayne@69 713 * @stable ICU 2.0
jpayne@69 714 */
jpayne@69 715 virtual UnicodeString& format(const Formattable& obj,
jpayne@69 716 UnicodeString& appendTo,
jpayne@69 717 FieldPosition& pos,
jpayne@69 718 UErrorCode& status) const;
jpayne@69 719
jpayne@69 720 /**
jpayne@69 721 * Formats the given array of arguments into a user-defined argument name
jpayne@69 722 * array. This function supports both named and numbered
jpayne@69 723 * arguments-- if numbered, the formatName is the
jpayne@69 724 * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
jpayne@69 725 *
jpayne@69 726 * @param argumentNames argument name array
jpayne@69 727 * @param arguments An array of objects to be formatted.
jpayne@69 728 * @param count The number of elements of 'argumentNames' and
jpayne@69 729 * arguments. The number of argumentNames and arguments
jpayne@69 730 * must be the same.
jpayne@69 731 * @param appendTo Output parameter to receive result.
jpayne@69 732 * Result is appended to existing contents.
jpayne@69 733 * @param status Input/output error code. If the
jpayne@69 734 * pattern cannot be parsed, set to failure code.
jpayne@69 735 * @return Reference to 'appendTo' parameter.
jpayne@69 736 * @stable ICU 4.0
jpayne@69 737 */
jpayne@69 738 UnicodeString& format(const UnicodeString* argumentNames,
jpayne@69 739 const Formattable* arguments,
jpayne@69 740 int32_t count,
jpayne@69 741 UnicodeString& appendTo,
jpayne@69 742 UErrorCode& status) const;
jpayne@69 743 /**
jpayne@69 744 * Parses the given string into an array of output arguments.
jpayne@69 745 *
jpayne@69 746 * @param source String to be parsed.
jpayne@69 747 * @param pos On input, starting position for parse. On output,
jpayne@69 748 * final position after parse. Unchanged if parse
jpayne@69 749 * fails.
jpayne@69 750 * @param count Output parameter to receive the number of arguments
jpayne@69 751 * parsed.
jpayne@69 752 * @return an array of parsed arguments. The caller owns both
jpayne@69 753 * the array and its contents.
jpayne@69 754 * @stable ICU 2.0
jpayne@69 755 */
jpayne@69 756 virtual Formattable* parse(const UnicodeString& source,
jpayne@69 757 ParsePosition& pos,
jpayne@69 758 int32_t& count) const;
jpayne@69 759
jpayne@69 760 /**
jpayne@69 761 * Parses the given string into an array of output arguments.
jpayne@69 762 *
jpayne@69 763 * <p>If this format uses named arguments, status is set to
jpayne@69 764 * U_ARGUMENT_TYPE_MISMATCH.
jpayne@69 765 *
jpayne@69 766 * @param source String to be parsed.
jpayne@69 767 * @param count Output param to receive size of returned array.
jpayne@69 768 * @param status Input/output error code. If the
jpayne@69 769 * pattern cannot be parsed, set to failure code.
jpayne@69 770 * @return an array of parsed arguments. The caller owns both
jpayne@69 771 * the array and its contents. Returns NULL if status is not U_ZERO_ERROR.
jpayne@69 772 *
jpayne@69 773 * @stable ICU 2.0
jpayne@69 774 */
jpayne@69 775 virtual Formattable* parse(const UnicodeString& source,
jpayne@69 776 int32_t& count,
jpayne@69 777 UErrorCode& status) const;
jpayne@69 778
jpayne@69 779 /**
jpayne@69 780 * Parses the given string into an array of output arguments
jpayne@69 781 * stored within a single Formattable of type kArray.
jpayne@69 782 *
jpayne@69 783 * @param source The string to be parsed into an object.
jpayne@69 784 * @param result Formattable to be set to the parse result.
jpayne@69 785 * If parse fails, return contents are undefined.
jpayne@69 786 * @param pos On input, starting position for parse. On output,
jpayne@69 787 * final position after parse. Unchanged if parse
jpayne@69 788 * fails.
jpayne@69 789 * @stable ICU 2.0
jpayne@69 790 */
jpayne@69 791 virtual void parseObject(const UnicodeString& source,
jpayne@69 792 Formattable& result,
jpayne@69 793 ParsePosition& pos) const;
jpayne@69 794
jpayne@69 795 /**
jpayne@69 796 * Convert an 'apostrophe-friendly' pattern into a standard
jpayne@69 797 * pattern. Standard patterns treat all apostrophes as
jpayne@69 798 * quotes, which is problematic in some languages, e.g.
jpayne@69 799 * French, where apostrophe is commonly used. This utility
jpayne@69 800 * assumes that only an unpaired apostrophe immediately before
jpayne@69 801 * a brace is a true quote. Other unpaired apostrophes are paired,
jpayne@69 802 * and the resulting standard pattern string is returned.
jpayne@69 803 *
jpayne@69 804 * <p><b>Note</b> it is not guaranteed that the returned pattern
jpayne@69 805 * is indeed a valid pattern. The only effect is to convert
jpayne@69 806 * between patterns having different quoting semantics.
jpayne@69 807 *
jpayne@69 808 * @param pattern the 'apostrophe-friendly' patttern to convert
jpayne@69 809 * @param status Input/output error code. If the pattern
jpayne@69 810 * cannot be parsed, the failure code is set.
jpayne@69 811 * @return the standard equivalent of the original pattern
jpayne@69 812 * @stable ICU 3.4
jpayne@69 813 */
jpayne@69 814 static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern,
jpayne@69 815 UErrorCode& status);
jpayne@69 816
jpayne@69 817
jpayne@69 818 /**
jpayne@69 819 * Returns true if this MessageFormat uses named arguments,
jpayne@69 820 * and false otherwise. See class description.
jpayne@69 821 *
jpayne@69 822 * @return true if named arguments are used.
jpayne@69 823 * @stable ICU 4.0
jpayne@69 824 */
jpayne@69 825 UBool usesNamedArguments() const;
jpayne@69 826
jpayne@69 827
jpayne@69 828 #ifndef U_HIDE_INTERNAL_API
jpayne@69 829 /**
jpayne@69 830 * This API is for ICU internal use only.
jpayne@69 831 * Please do not use it.
jpayne@69 832 *
jpayne@69 833 * Returns argument types count in the parsed pattern.
jpayne@69 834 * Used to distinguish pattern "{0} d" and "d".
jpayne@69 835 *
jpayne@69 836 * @return The number of formattable types in the pattern
jpayne@69 837 * @internal
jpayne@69 838 */
jpayne@69 839 int32_t getArgTypeCount() const;
jpayne@69 840 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 841
jpayne@69 842 /**
jpayne@69 843 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
jpayne@69 844 * This method is to implement a simple version of RTTI, since not all
jpayne@69 845 * C++ compilers support genuine RTTI. Polymorphic operator==() and
jpayne@69 846 * clone() methods call this method.
jpayne@69 847 *
jpayne@69 848 * @return The class ID for this object. All objects of a
jpayne@69 849 * given class have the same class ID. Objects of
jpayne@69 850 * other classes have different class IDs.
jpayne@69 851 * @stable ICU 2.0
jpayne@69 852 */
jpayne@69 853 virtual UClassID getDynamicClassID(void) const;
jpayne@69 854
jpayne@69 855 /**
jpayne@69 856 * Return the class ID for this class. This is useful only for
jpayne@69 857 * comparing to a return value from getDynamicClassID(). For example:
jpayne@69 858 * <pre>
jpayne@69 859 * . Base* polymorphic_pointer = createPolymorphicObject();
jpayne@69 860 * . if (polymorphic_pointer->getDynamicClassID() ==
jpayne@69 861 * . Derived::getStaticClassID()) ...
jpayne@69 862 * </pre>
jpayne@69 863 * @return The class ID for all objects of this class.
jpayne@69 864 * @stable ICU 2.0
jpayne@69 865 */
jpayne@69 866 static UClassID U_EXPORT2 getStaticClassID(void);
jpayne@69 867
jpayne@69 868 #ifndef U_HIDE_INTERNAL_API
jpayne@69 869 /**
jpayne@69 870 * Compares two Format objects. This is used for constructing the hash
jpayne@69 871 * tables.
jpayne@69 872 *
jpayne@69 873 * @param left pointer to a Format object. Must not be NULL.
jpayne@69 874 * @param right pointer to a Format object. Must not be NULL.
jpayne@69 875 *
jpayne@69 876 * @return whether the two objects are the same
jpayne@69 877 * @internal
jpayne@69 878 */
jpayne@69 879 static UBool equalFormats(const void* left, const void* right);
jpayne@69 880 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 881
jpayne@69 882 private:
jpayne@69 883
jpayne@69 884 Locale fLocale;
jpayne@69 885 MessagePattern msgPattern;
jpayne@69 886 Format** formatAliases; // see getFormats
jpayne@69 887 int32_t formatAliasesCapacity;
jpayne@69 888
jpayne@69 889 MessageFormat(); // default constructor not implemented
jpayne@69 890
jpayne@69 891 /**
jpayne@69 892 * This provider helps defer instantiation of a PluralRules object
jpayne@69 893 * until we actually need to select a keyword.
jpayne@69 894 * For example, if the number matches an explicit-value selector like "=1"
jpayne@69 895 * we do not need any PluralRules.
jpayne@69 896 */
jpayne@69 897 class U_I18N_API PluralSelectorProvider : public PluralFormat::PluralSelector {
jpayne@69 898 public:
jpayne@69 899 PluralSelectorProvider(const MessageFormat &mf, UPluralType type);
jpayne@69 900 virtual ~PluralSelectorProvider();
jpayne@69 901 virtual UnicodeString select(void *ctx, double number, UErrorCode& ec) const;
jpayne@69 902
jpayne@69 903 void reset();
jpayne@69 904 private:
jpayne@69 905 const MessageFormat &msgFormat;
jpayne@69 906 PluralRules* rules;
jpayne@69 907 UPluralType type;
jpayne@69 908 };
jpayne@69 909
jpayne@69 910 /**
jpayne@69 911 * A MessageFormat formats an array of arguments. Each argument
jpayne@69 912 * has an expected type, based on the pattern. For example, if
jpayne@69 913 * the pattern contains the subformat "{3,number,integer}", then
jpayne@69 914 * we expect argument 3 to have type Formattable::kLong. This
jpayne@69 915 * array needs to grow dynamically if the MessageFormat is
jpayne@69 916 * modified.
jpayne@69 917 */
jpayne@69 918 Formattable::Type* argTypes;
jpayne@69 919 int32_t argTypeCount;
jpayne@69 920 int32_t argTypeCapacity;
jpayne@69 921
jpayne@69 922 /**
jpayne@69 923 * TRUE if there are different argTypes for the same argument.
jpayne@69 924 * This only matters when the MessageFormat is used in the plain C (umsg_xxx) API
jpayne@69 925 * where the pattern argTypes determine how the va_arg list is read.
jpayne@69 926 */
jpayne@69 927 UBool hasArgTypeConflicts;
jpayne@69 928
jpayne@69 929 // Variable-size array management
jpayne@69 930 UBool allocateArgTypes(int32_t capacity, UErrorCode& status);
jpayne@69 931
jpayne@69 932 /**
jpayne@69 933 * Default Format objects used when no format is specified and a
jpayne@69 934 * numeric or date argument is formatted. These are volatile
jpayne@69 935 * cache objects maintained only for performance. They do not
jpayne@69 936 * participate in operator=(), copy constructor(), nor
jpayne@69 937 * operator==().
jpayne@69 938 */
jpayne@69 939 NumberFormat* defaultNumberFormat;
jpayne@69 940 DateFormat* defaultDateFormat;
jpayne@69 941
jpayne@69 942 UHashtable* cachedFormatters;
jpayne@69 943 UHashtable* customFormatArgStarts;
jpayne@69 944
jpayne@69 945 PluralSelectorProvider pluralProvider;
jpayne@69 946 PluralSelectorProvider ordinalProvider;
jpayne@69 947
jpayne@69 948 /**
jpayne@69 949 * Method to retrieve default formats (or NULL on failure).
jpayne@69 950 * These are semantically const, but may modify *this.
jpayne@69 951 */
jpayne@69 952 const NumberFormat* getDefaultNumberFormat(UErrorCode&) const;
jpayne@69 953 const DateFormat* getDefaultDateFormat(UErrorCode&) const;
jpayne@69 954
jpayne@69 955 /**
jpayne@69 956 * Finds the word s, in the keyword list and returns the located index.
jpayne@69 957 * @param s the keyword to be searched for.
jpayne@69 958 * @param list the list of keywords to be searched with.
jpayne@69 959 * @return the index of the list which matches the keyword s.
jpayne@69 960 */
jpayne@69 961 static int32_t findKeyword( const UnicodeString& s,
jpayne@69 962 const char16_t * const *list);
jpayne@69 963
jpayne@69 964 /**
jpayne@69 965 * Thin wrapper around the format(... AppendableWrapper ...) variant.
jpayne@69 966 * Wraps the destination UnicodeString into an AppendableWrapper and
jpayne@69 967 * supplies default values for some other parameters.
jpayne@69 968 */
jpayne@69 969 UnicodeString& format(const Formattable* arguments,
jpayne@69 970 const UnicodeString *argumentNames,
jpayne@69 971 int32_t cnt,
jpayne@69 972 UnicodeString& appendTo,
jpayne@69 973 FieldPosition* pos,
jpayne@69 974 UErrorCode& status) const;
jpayne@69 975
jpayne@69 976 /**
jpayne@69 977 * Formats the arguments and writes the result into the
jpayne@69 978 * AppendableWrapper, updates the field position.
jpayne@69 979 *
jpayne@69 980 * @param msgStart Index to msgPattern part to start formatting from.
jpayne@69 981 * @param plNumber NULL except when formatting a plural argument sub-message
jpayne@69 982 * where a '#' is replaced by the format string for this number.
jpayne@69 983 * @param arguments The formattable objects array. (Must not be NULL.)
jpayne@69 984 * @param argumentNames NULL if numbered values are used. Otherwise the same
jpayne@69 985 * length as "arguments", and each entry is the name of the
jpayne@69 986 * corresponding argument in "arguments".
jpayne@69 987 * @param cnt The length of arguments (and of argumentNames if that is not NULL).
jpayne@69 988 * @param appendTo Output parameter to receive the result.
jpayne@69 989 * The result string is appended to existing contents.
jpayne@69 990 * @param pos Field position status.
jpayne@69 991 * @param success The error code status.
jpayne@69 992 */
jpayne@69 993 void format(int32_t msgStart,
jpayne@69 994 const void *plNumber,
jpayne@69 995 const Formattable* arguments,
jpayne@69 996 const UnicodeString *argumentNames,
jpayne@69 997 int32_t cnt,
jpayne@69 998 AppendableWrapper& appendTo,
jpayne@69 999 FieldPosition* pos,
jpayne@69 1000 UErrorCode& success) const;
jpayne@69 1001
jpayne@69 1002 UnicodeString getArgName(int32_t partIndex);
jpayne@69 1003
jpayne@69 1004 void setArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status);
jpayne@69 1005
jpayne@69 1006 void setCustomArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status);
jpayne@69 1007
jpayne@69 1008 int32_t nextTopLevelArgStart(int32_t partIndex) const;
jpayne@69 1009
jpayne@69 1010 UBool argNameMatches(int32_t partIndex, const UnicodeString& argName, int32_t argNumber);
jpayne@69 1011
jpayne@69 1012 void cacheExplicitFormats(UErrorCode& status);
jpayne@69 1013
jpayne@69 1014 int32_t skipLeadingSpaces(UnicodeString& style);
jpayne@69 1015
jpayne@69 1016 Format* createAppropriateFormat(UnicodeString& type,
jpayne@69 1017 UnicodeString& style,
jpayne@69 1018 Formattable::Type& formattableType,
jpayne@69 1019 UParseError& parseError,
jpayne@69 1020 UErrorCode& ec);
jpayne@69 1021
jpayne@69 1022 const Formattable* getArgFromListByName(const Formattable* arguments,
jpayne@69 1023 const UnicodeString *argumentNames,
jpayne@69 1024 int32_t cnt, UnicodeString& name) const;
jpayne@69 1025
jpayne@69 1026 Formattable* parse(int32_t msgStart,
jpayne@69 1027 const UnicodeString& source,
jpayne@69 1028 ParsePosition& pos,
jpayne@69 1029 int32_t& count,
jpayne@69 1030 UErrorCode& ec) const;
jpayne@69 1031
jpayne@69 1032 FieldPosition* updateMetaData(AppendableWrapper& dest, int32_t prevLength,
jpayne@69 1033 FieldPosition* fp, const Formattable* argId) const;
jpayne@69 1034
jpayne@69 1035 /**
jpayne@69 1036 * Finds the "other" sub-message.
jpayne@69 1037 * @param partIndex the index of the first PluralFormat argument style part.
jpayne@69 1038 * @return the "other" sub-message start part index.
jpayne@69 1039 */
jpayne@69 1040 int32_t findOtherSubMessage(int32_t partIndex) const;
jpayne@69 1041
jpayne@69 1042 /**
jpayne@69 1043 * Returns the ARG_START index of the first occurrence of the plural number in a sub-message.
jpayne@69 1044 * Returns -1 if it is a REPLACE_NUMBER.
jpayne@69 1045 * Returns 0 if there is neither.
jpayne@69 1046 */
jpayne@69 1047 int32_t findFirstPluralNumberArg(int32_t msgStart, const UnicodeString &argName) const;
jpayne@69 1048
jpayne@69 1049 Format* getCachedFormatter(int32_t argumentNumber) const;
jpayne@69 1050
jpayne@69 1051 UnicodeString getLiteralStringUntilNextArgument(int32_t from) const;
jpayne@69 1052
jpayne@69 1053 void copyObjects(const MessageFormat& that, UErrorCode& ec);
jpayne@69 1054
jpayne@69 1055 void formatComplexSubMessage(int32_t msgStart,
jpayne@69 1056 const void *plNumber,
jpayne@69 1057 const Formattable* arguments,
jpayne@69 1058 const UnicodeString *argumentNames,
jpayne@69 1059 int32_t cnt,
jpayne@69 1060 AppendableWrapper& appendTo,
jpayne@69 1061 UErrorCode& success) const;
jpayne@69 1062
jpayne@69 1063 /**
jpayne@69 1064 * Convenience method that ought to be in NumberFormat
jpayne@69 1065 */
jpayne@69 1066 NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const;
jpayne@69 1067
jpayne@69 1068 /**
jpayne@69 1069 * Returns array of argument types in the parsed pattern
jpayne@69 1070 * for use in C API. Only for the use of umsg_vformat(). Not
jpayne@69 1071 * for public consumption.
jpayne@69 1072 * @param listCount Output parameter to receive the size of array
jpayne@69 1073 * @return The array of formattable types in the pattern
jpayne@69 1074 */
jpayne@69 1075 const Formattable::Type* getArgTypeList(int32_t& listCount) const {
jpayne@69 1076 listCount = argTypeCount;
jpayne@69 1077 return argTypes;
jpayne@69 1078 }
jpayne@69 1079
jpayne@69 1080 /**
jpayne@69 1081 * Resets the internal MessagePattern, and other associated caches.
jpayne@69 1082 */
jpayne@69 1083 void resetPattern();
jpayne@69 1084
jpayne@69 1085 /**
jpayne@69 1086 * A DummyFormatter that we use solely to store a NULL value. UHash does
jpayne@69 1087 * not support storing NULL values.
jpayne@69 1088 */
jpayne@69 1089 class U_I18N_API DummyFormat : public Format {
jpayne@69 1090 public:
jpayne@69 1091 virtual UBool operator==(const Format&) const;
jpayne@69 1092 virtual DummyFormat* clone() const;
jpayne@69 1093 virtual UnicodeString& format(const Formattable& obj,
jpayne@69 1094 UnicodeString& appendTo,
jpayne@69 1095 UErrorCode& status) const;
jpayne@69 1096 virtual UnicodeString& format(const Formattable&,
jpayne@69 1097 UnicodeString& appendTo,
jpayne@69 1098 FieldPosition&,
jpayne@69 1099 UErrorCode& status) const;
jpayne@69 1100 virtual UnicodeString& format(const Formattable& obj,
jpayne@69 1101 UnicodeString& appendTo,
jpayne@69 1102 FieldPositionIterator* posIter,
jpayne@69 1103 UErrorCode& status) const;
jpayne@69 1104 virtual void parseObject(const UnicodeString&,
jpayne@69 1105 Formattable&,
jpayne@69 1106 ParsePosition&) const;
jpayne@69 1107 };
jpayne@69 1108
jpayne@69 1109 friend class MessageFormatAdapter; // getFormatTypeList() access
jpayne@69 1110 };
jpayne@69 1111
jpayne@69 1112 U_NAMESPACE_END
jpayne@69 1113
jpayne@69 1114 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 1115
jpayne@69 1116 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 1117
jpayne@69 1118 #endif // _MSGFMT
jpayne@69 1119 //eof