Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/umsg.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:
jpayne@69 5 * Copyright (c) 1997-2011, International Business Machines Corporation and
jpayne@69 6 * others. All Rights Reserved.
jpayne@69 7 * Copyright (C) 2010 , Yahoo! Inc.
jpayne@69 8 ********************************************************************
jpayne@69 9 *
jpayne@69 10 * file name: umsg.h
jpayne@69 11 * encoding: UTF-8
jpayne@69 12 * tab size: 8 (not used)
jpayne@69 13 * indentation:4
jpayne@69 14 *
jpayne@69 15 * Change history:
jpayne@69 16 *
jpayne@69 17 * 08/5/2001 Ram Added C wrappers for C++ API.
jpayne@69 18 ********************************************************************/
jpayne@69 19
jpayne@69 20 #ifndef UMSG_H
jpayne@69 21 #define UMSG_H
jpayne@69 22
jpayne@69 23 #include "unicode/utypes.h"
jpayne@69 24
jpayne@69 25 #if !UCONFIG_NO_FORMATTING
jpayne@69 26
jpayne@69 27 #include "unicode/localpointer.h"
jpayne@69 28 #include "unicode/uloc.h"
jpayne@69 29 #include "unicode/parseerr.h"
jpayne@69 30 #include <stdarg.h>
jpayne@69 31
jpayne@69 32 /**
jpayne@69 33 * \file
jpayne@69 34 * \brief C API: MessageFormat
jpayne@69 35 *
jpayne@69 36 * <h2>MessageFormat C API </h2>
jpayne@69 37 *
jpayne@69 38 * <p>MessageFormat prepares strings for display to users,
jpayne@69 39 * with optional arguments (variables/placeholders).
jpayne@69 40 * The arguments can occur in any order, which is necessary for translation
jpayne@69 41 * into languages with different grammars.
jpayne@69 42 *
jpayne@69 43 * <p>The opaque UMessageFormat type is a thin C wrapper around
jpayne@69 44 * a C++ MessageFormat. It is constructed from a <em>pattern</em> string
jpayne@69 45 * with arguments in {curly braces} which will be replaced by formatted values.
jpayne@69 46 *
jpayne@69 47 * <p>Currently, the C API supports only numbered arguments.
jpayne@69 48 *
jpayne@69 49 * <p>For details about the pattern syntax and behavior,
jpayne@69 50 * especially about the ASCII apostrophe vs. the
jpayne@69 51 * real apostrophe (single quote) character \htmlonly&#x2019;\endhtmlonly (U+2019),
jpayne@69 52 * see the C++ MessageFormat class documentation.
jpayne@69 53 *
jpayne@69 54 * <p>Here are some examples of C API usage:
jpayne@69 55 * Example 1:
jpayne@69 56 * <pre>
jpayne@69 57 * \code
jpayne@69 58 * UChar *result, *tzID, *str;
jpayne@69 59 * UChar pattern[100];
jpayne@69 60 * int32_t resultLengthOut, resultlength;
jpayne@69 61 * UCalendar *cal;
jpayne@69 62 * UDate d1;
jpayne@69 63 * UDateFormat *def1;
jpayne@69 64 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 65 *
jpayne@69 66 * str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
jpayne@69 67 * u_uastrcpy(str, "disturbance in force");
jpayne@69 68 * tzID=(UChar*)malloc(sizeof(UChar) * 4);
jpayne@69 69 * u_uastrcpy(tzID, "PST");
jpayne@69 70 * cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
jpayne@69 71 * ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
jpayne@69 72 * d1=ucal_getMillis(cal, &status);
jpayne@69 73 * u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet {2,number,integer}");
jpayne@69 74 * resultlength=0;
jpayne@69 75 * resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, d1, str, 7);
jpayne@69 76 * if(status==U_BUFFER_OVERFLOW_ERROR){
jpayne@69 77 * status=U_ZERO_ERROR;
jpayne@69 78 * resultlength=resultLengthOut+1;
jpayne@69 79 * result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
jpayne@69 80 * u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, d1, str, 7);
jpayne@69 81 * }
jpayne@69 82 * printf("%s\n", austrdup(result) );//austrdup( a function used to convert UChar* to char*)
jpayne@69 83 * //output>: "On March 18, 1999, there was a disturbance in force on planet 7
jpayne@69 84 * \endcode
jpayne@69 85 * </pre>
jpayne@69 86 * Typically, the message format will come from resources, and the
jpayne@69 87 * arguments will be dynamically set at runtime.
jpayne@69 88 * <P>
jpayne@69 89 * Example 2:
jpayne@69 90 * <pre>
jpayne@69 91 * \code
jpayne@69 92 * UChar* str;
jpayne@69 93 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 94 * UChar *result;
jpayne@69 95 * UChar pattern[100];
jpayne@69 96 * int32_t resultlength, resultLengthOut, i;
jpayne@69 97 * double testArgs= { 100.0, 1.0, 0.0};
jpayne@69 98 *
jpayne@69 99 * str=(UChar*)malloc(sizeof(UChar) * 10);
jpayne@69 100 * u_uastrcpy(str, "MyDisk");
jpayne@69 101 * u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one file|1<{0,number,integer} files}");
jpayne@69 102 * for(i=0; i<3; i++){
jpayne@69 103 * resultlength=0;
jpayne@69 104 * resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str);
jpayne@69 105 * if(status==U_BUFFER_OVERFLOW_ERROR){
jpayne@69 106 * status=U_ZERO_ERROR;
jpayne@69 107 * resultlength=resultLengthOut+1;
jpayne@69 108 * result=(UChar*)malloc(sizeof(UChar) * resultlength);
jpayne@69 109 * u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, testArgs[i], str);
jpayne@69 110 * }
jpayne@69 111 * printf("%s\n", austrdup(result) ); //austrdup( a function used to convert UChar* to char*)
jpayne@69 112 * free(result);
jpayne@69 113 * }
jpayne@69 114 * // output, with different testArgs:
jpayne@69 115 * // output: The disk "MyDisk" contains 100 files.
jpayne@69 116 * // output: The disk "MyDisk" contains one file.
jpayne@69 117 * // output: The disk "MyDisk" contains no files.
jpayne@69 118 * \endcode
jpayne@69 119 * </pre>
jpayne@69 120 *
jpayne@69 121 *
jpayne@69 122 * Example 3:
jpayne@69 123 * <pre>
jpayne@69 124 * \code
jpayne@69 125 * UChar* str;
jpayne@69 126 * UChar* str1;
jpayne@69 127 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 128 * UChar *result;
jpayne@69 129 * UChar pattern[100];
jpayne@69 130 * UChar expected[100];
jpayne@69 131 * int32_t resultlength,resultLengthOut;
jpayne@69 132
jpayne@69 133 * str=(UChar*)malloc(sizeof(UChar) * 25);
jpayne@69 134 * u_uastrcpy(str, "Kirti");
jpayne@69 135 * str1=(UChar*)malloc(sizeof(UChar) * 25);
jpayne@69 136 * u_uastrcpy(str1, "female");
jpayne@69 137 * log_verbose("Testing message format with Select test #1\n:");
jpayne@69 138 * u_uastrcpy(pattern, "{0} est {1, select, female {all\\u00E9e} other {all\\u00E9}} \\u00E0 Paris.");
jpayne@69 139 * u_uastrcpy(expected, "Kirti est all\\u00E9e \\u00E0 Paris.");
jpayne@69 140 * resultlength=0;
jpayne@69 141 * resultLengthOut=u_formatMessage( "fr", pattern, u_strlen(pattern), NULL, resultlength, &status, str , str1);
jpayne@69 142 * if(status==U_BUFFER_OVERFLOW_ERROR)
jpayne@69 143 * {
jpayne@69 144 * status=U_ZERO_ERROR;
jpayne@69 145 * resultlength=resultLengthOut+1;
jpayne@69 146 * result=(UChar*)malloc(sizeof(UChar) * resultlength);
jpayne@69 147 * u_formatMessage( "fr", pattern, u_strlen(pattern), result, resultlength, &status, str , str1);
jpayne@69 148 * if(u_strcmp(result, expected)==0)
jpayne@69 149 * log_verbose("PASS: MessagFormat successful on Select test#1\n");
jpayne@69 150 * else{
jpayne@69 151 * log_err("FAIL: Error in MessageFormat on Select test#1\n GOT %s EXPECTED %s\n", austrdup(result),
jpayne@69 152 * austrdup(expected) );
jpayne@69 153 * }
jpayne@69 154 * free(result);
jpayne@69 155 * }
jpayne@69 156 * \endcode
jpayne@69 157 * </pre>
jpayne@69 158 */
jpayne@69 159
jpayne@69 160 /**
jpayne@69 161 * Format a message for a locale.
jpayne@69 162 * This function may perform re-ordering of the arguments depending on the
jpayne@69 163 * locale. For all numeric arguments, double is assumed unless the type is
jpayne@69 164 * explicitly integer. All choice format arguments must be of type double.
jpayne@69 165 * @param locale The locale for which the message will be formatted
jpayne@69 166 * @param pattern The pattern specifying the message's format
jpayne@69 167 * @param patternLength The length of pattern
jpayne@69 168 * @param result A pointer to a buffer to receive the formatted message.
jpayne@69 169 * @param resultLength The maximum size of result.
jpayne@69 170 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 171 * @param ... A variable-length argument list containing the arguments specified
jpayne@69 172 * in pattern.
jpayne@69 173 * @return The total buffer size needed; if greater than resultLength, the
jpayne@69 174 * output was truncated.
jpayne@69 175 * @see u_parseMessage
jpayne@69 176 * @stable ICU 2.0
jpayne@69 177 */
jpayne@69 178 U_STABLE int32_t U_EXPORT2
jpayne@69 179 u_formatMessage(const char *locale,
jpayne@69 180 const UChar *pattern,
jpayne@69 181 int32_t patternLength,
jpayne@69 182 UChar *result,
jpayne@69 183 int32_t resultLength,
jpayne@69 184 UErrorCode *status,
jpayne@69 185 ...);
jpayne@69 186
jpayne@69 187 /**
jpayne@69 188 * Format a message for a locale.
jpayne@69 189 * This function may perform re-ordering of the arguments depending on the
jpayne@69 190 * locale. For all numeric arguments, double is assumed unless the type is
jpayne@69 191 * explicitly integer. All choice format arguments must be of type double.
jpayne@69 192 * @param locale The locale for which the message will be formatted
jpayne@69 193 * @param pattern The pattern specifying the message's format
jpayne@69 194 * @param patternLength The length of pattern
jpayne@69 195 * @param result A pointer to a buffer to receive the formatted message.
jpayne@69 196 * @param resultLength The maximum size of result.
jpayne@69 197 * @param ap A variable-length argument list containing the arguments specified
jpayne@69 198 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 199 * in pattern.
jpayne@69 200 * @return The total buffer size needed; if greater than resultLength, the
jpayne@69 201 * output was truncated.
jpayne@69 202 * @see u_parseMessage
jpayne@69 203 * @stable ICU 2.0
jpayne@69 204 */
jpayne@69 205 U_STABLE int32_t U_EXPORT2
jpayne@69 206 u_vformatMessage( const char *locale,
jpayne@69 207 const UChar *pattern,
jpayne@69 208 int32_t patternLength,
jpayne@69 209 UChar *result,
jpayne@69 210 int32_t resultLength,
jpayne@69 211 va_list ap,
jpayne@69 212 UErrorCode *status);
jpayne@69 213
jpayne@69 214 /**
jpayne@69 215 * Parse a message.
jpayne@69 216 * For numeric arguments, this function will always use doubles. Integer types
jpayne@69 217 * should not be passed.
jpayne@69 218 * This function is not able to parse all output from {@link #u_formatMessage }.
jpayne@69 219 * @param locale The locale for which the message is formatted
jpayne@69 220 * @param pattern The pattern specifying the message's format
jpayne@69 221 * @param patternLength The length of pattern
jpayne@69 222 * @param source The text to parse.
jpayne@69 223 * @param sourceLength The length of source, or -1 if null-terminated.
jpayne@69 224 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 225 * @param ... A variable-length argument list containing the arguments
jpayne@69 226 * specified in pattern.
jpayne@69 227 * @see u_formatMessage
jpayne@69 228 * @stable ICU 2.0
jpayne@69 229 */
jpayne@69 230 U_STABLE void U_EXPORT2
jpayne@69 231 u_parseMessage( const char *locale,
jpayne@69 232 const UChar *pattern,
jpayne@69 233 int32_t patternLength,
jpayne@69 234 const UChar *source,
jpayne@69 235 int32_t sourceLength,
jpayne@69 236 UErrorCode *status,
jpayne@69 237 ...);
jpayne@69 238
jpayne@69 239 /**
jpayne@69 240 * Parse a message.
jpayne@69 241 * For numeric arguments, this function will always use doubles. Integer types
jpayne@69 242 * should not be passed.
jpayne@69 243 * This function is not able to parse all output from {@link #u_formatMessage }.
jpayne@69 244 * @param locale The locale for which the message is formatted
jpayne@69 245 * @param pattern The pattern specifying the message's format
jpayne@69 246 * @param patternLength The length of pattern
jpayne@69 247 * @param source The text to parse.
jpayne@69 248 * @param sourceLength The length of source, or -1 if null-terminated.
jpayne@69 249 * @param ap A variable-length argument list containing the arguments
jpayne@69 250 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 251 * specified in pattern.
jpayne@69 252 * @see u_formatMessage
jpayne@69 253 * @stable ICU 2.0
jpayne@69 254 */
jpayne@69 255 U_STABLE void U_EXPORT2
jpayne@69 256 u_vparseMessage(const char *locale,
jpayne@69 257 const UChar *pattern,
jpayne@69 258 int32_t patternLength,
jpayne@69 259 const UChar *source,
jpayne@69 260 int32_t sourceLength,
jpayne@69 261 va_list ap,
jpayne@69 262 UErrorCode *status);
jpayne@69 263
jpayne@69 264 /**
jpayne@69 265 * Format a message for a locale.
jpayne@69 266 * This function may perform re-ordering of the arguments depending on the
jpayne@69 267 * locale. For all numeric arguments, double is assumed unless the type is
jpayne@69 268 * explicitly integer. All choice format arguments must be of type double.
jpayne@69 269 * @param locale The locale for which the message will be formatted
jpayne@69 270 * @param pattern The pattern specifying the message's format
jpayne@69 271 * @param patternLength The length of pattern
jpayne@69 272 * @param result A pointer to a buffer to receive the formatted message.
jpayne@69 273 * @param resultLength The maximum size of result.
jpayne@69 274 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 275 * @param ... A variable-length argument list containing the arguments specified
jpayne@69 276 * in pattern.
jpayne@69 277 * @param parseError A pointer to UParseError to receive information about errors
jpayne@69 278 * occurred during parsing.
jpayne@69 279 * @return The total buffer size needed; if greater than resultLength, the
jpayne@69 280 * output was truncated.
jpayne@69 281 * @see u_parseMessage
jpayne@69 282 * @stable ICU 2.0
jpayne@69 283 */
jpayne@69 284 U_STABLE int32_t U_EXPORT2
jpayne@69 285 u_formatMessageWithError( const char *locale,
jpayne@69 286 const UChar *pattern,
jpayne@69 287 int32_t patternLength,
jpayne@69 288 UChar *result,
jpayne@69 289 int32_t resultLength,
jpayne@69 290 UParseError *parseError,
jpayne@69 291 UErrorCode *status,
jpayne@69 292 ...);
jpayne@69 293
jpayne@69 294 /**
jpayne@69 295 * Format a message for a locale.
jpayne@69 296 * This function may perform re-ordering of the arguments depending on the
jpayne@69 297 * locale. For all numeric arguments, double is assumed unless the type is
jpayne@69 298 * explicitly integer. All choice format arguments must be of type double.
jpayne@69 299 * @param locale The locale for which the message will be formatted
jpayne@69 300 * @param pattern The pattern specifying the message's format
jpayne@69 301 * @param patternLength The length of pattern
jpayne@69 302 * @param result A pointer to a buffer to receive the formatted message.
jpayne@69 303 * @param resultLength The maximum size of result.
jpayne@69 304 * @param parseError A pointer to UParseError to receive information about errors
jpayne@69 305 * occurred during parsing.
jpayne@69 306 * @param ap A variable-length argument list containing the arguments specified
jpayne@69 307 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 308 * in pattern.
jpayne@69 309 * @return The total buffer size needed; if greater than resultLength, the
jpayne@69 310 * output was truncated.
jpayne@69 311 * @stable ICU 2.0
jpayne@69 312 */
jpayne@69 313 U_STABLE int32_t U_EXPORT2
jpayne@69 314 u_vformatMessageWithError( const char *locale,
jpayne@69 315 const UChar *pattern,
jpayne@69 316 int32_t patternLength,
jpayne@69 317 UChar *result,
jpayne@69 318 int32_t resultLength,
jpayne@69 319 UParseError* parseError,
jpayne@69 320 va_list ap,
jpayne@69 321 UErrorCode *status);
jpayne@69 322
jpayne@69 323 /**
jpayne@69 324 * Parse a message.
jpayne@69 325 * For numeric arguments, this function will always use doubles. Integer types
jpayne@69 326 * should not be passed.
jpayne@69 327 * This function is not able to parse all output from {@link #u_formatMessage }.
jpayne@69 328 * @param locale The locale for which the message is formatted
jpayne@69 329 * @param pattern The pattern specifying the message's format
jpayne@69 330 * @param patternLength The length of pattern
jpayne@69 331 * @param source The text to parse.
jpayne@69 332 * @param sourceLength The length of source, or -1 if null-terminated.
jpayne@69 333 * @param parseError A pointer to UParseError to receive information about errors
jpayne@69 334 * occurred during parsing.
jpayne@69 335 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 336 * @param ... A variable-length argument list containing the arguments
jpayne@69 337 * specified in pattern.
jpayne@69 338 * @see u_formatMessage
jpayne@69 339 * @stable ICU 2.0
jpayne@69 340 */
jpayne@69 341 U_STABLE void U_EXPORT2
jpayne@69 342 u_parseMessageWithError(const char *locale,
jpayne@69 343 const UChar *pattern,
jpayne@69 344 int32_t patternLength,
jpayne@69 345 const UChar *source,
jpayne@69 346 int32_t sourceLength,
jpayne@69 347 UParseError *parseError,
jpayne@69 348 UErrorCode *status,
jpayne@69 349 ...);
jpayne@69 350
jpayne@69 351 /**
jpayne@69 352 * Parse a message.
jpayne@69 353 * For numeric arguments, this function will always use doubles. Integer types
jpayne@69 354 * should not be passed.
jpayne@69 355 * This function is not able to parse all output from {@link #u_formatMessage }.
jpayne@69 356 * @param locale The locale for which the message is formatted
jpayne@69 357 * @param pattern The pattern specifying the message's format
jpayne@69 358 * @param patternLength The length of pattern
jpayne@69 359 * @param source The text to parse.
jpayne@69 360 * @param sourceLength The length of source, or -1 if null-terminated.
jpayne@69 361 * @param ap A variable-length argument list containing the arguments
jpayne@69 362 * @param parseError A pointer to UParseError to receive information about errors
jpayne@69 363 * occurred during parsing.
jpayne@69 364 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 365 * specified in pattern.
jpayne@69 366 * @see u_formatMessage
jpayne@69 367 * @stable ICU 2.0
jpayne@69 368 */
jpayne@69 369 U_STABLE void U_EXPORT2
jpayne@69 370 u_vparseMessageWithError(const char *locale,
jpayne@69 371 const UChar *pattern,
jpayne@69 372 int32_t patternLength,
jpayne@69 373 const UChar *source,
jpayne@69 374 int32_t sourceLength,
jpayne@69 375 va_list ap,
jpayne@69 376 UParseError *parseError,
jpayne@69 377 UErrorCode* status);
jpayne@69 378
jpayne@69 379 /*----------------------- New experimental API --------------------------- */
jpayne@69 380 /**
jpayne@69 381 * The message format object
jpayne@69 382 * @stable ICU 2.0
jpayne@69 383 */
jpayne@69 384 typedef void* UMessageFormat;
jpayne@69 385
jpayne@69 386
jpayne@69 387 /**
jpayne@69 388 * Open a message formatter with given pattern and for the given locale.
jpayne@69 389 * @param pattern A pattern specifying the format to use.
jpayne@69 390 * @param patternLength Length of the pattern to use
jpayne@69 391 * @param locale The locale for which the messages are formatted.
jpayne@69 392 * @param parseError A pointer to UParseError struct to receive any errors
jpayne@69 393 * occured during parsing. Can be NULL.
jpayne@69 394 * @param status A pointer to an UErrorCode to receive any errors.
jpayne@69 395 * @return A pointer to a UMessageFormat to use for formatting
jpayne@69 396 * messages, or 0 if an error occurred.
jpayne@69 397 * @stable ICU 2.0
jpayne@69 398 */
jpayne@69 399 U_STABLE UMessageFormat* U_EXPORT2
jpayne@69 400 umsg_open( const UChar *pattern,
jpayne@69 401 int32_t patternLength,
jpayne@69 402 const char *locale,
jpayne@69 403 UParseError *parseError,
jpayne@69 404 UErrorCode *status);
jpayne@69 405
jpayne@69 406 /**
jpayne@69 407 * Close a UMessageFormat.
jpayne@69 408 * Once closed, a UMessageFormat may no longer be used.
jpayne@69 409 * @param format The formatter to close.
jpayne@69 410 * @stable ICU 2.0
jpayne@69 411 */
jpayne@69 412 U_STABLE void U_EXPORT2
jpayne@69 413 umsg_close(UMessageFormat* format);
jpayne@69 414
jpayne@69 415 #if U_SHOW_CPLUSPLUS_API
jpayne@69 416
jpayne@69 417 U_NAMESPACE_BEGIN
jpayne@69 418
jpayne@69 419 /**
jpayne@69 420 * \class LocalUMessageFormatPointer
jpayne@69 421 * "Smart pointer" class, closes a UMessageFormat via umsg_close().
jpayne@69 422 * For most methods see the LocalPointerBase base class.
jpayne@69 423 *
jpayne@69 424 * @see LocalPointerBase
jpayne@69 425 * @see LocalPointer
jpayne@69 426 * @stable ICU 4.4
jpayne@69 427 */
jpayne@69 428 U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close);
jpayne@69 429
jpayne@69 430 U_NAMESPACE_END
jpayne@69 431
jpayne@69 432 #endif
jpayne@69 433
jpayne@69 434 /**
jpayne@69 435 * Open a copy of a UMessageFormat.
jpayne@69 436 * This function performs a deep copy.
jpayne@69 437 * @param fmt The formatter to copy
jpayne@69 438 * @param status A pointer to an UErrorCode to receive any errors.
jpayne@69 439 * @return A pointer to a UDateFormat identical to fmt.
jpayne@69 440 * @stable ICU 2.0
jpayne@69 441 */
jpayne@69 442 U_STABLE UMessageFormat U_EXPORT2
jpayne@69 443 umsg_clone(const UMessageFormat *fmt,
jpayne@69 444 UErrorCode *status);
jpayne@69 445
jpayne@69 446 /**
jpayne@69 447 * Sets the locale. This locale is used for fetching default number or date
jpayne@69 448 * format information.
jpayne@69 449 * @param fmt The formatter to set
jpayne@69 450 * @param locale The locale the formatter should use.
jpayne@69 451 * @stable ICU 2.0
jpayne@69 452 */
jpayne@69 453 U_STABLE void U_EXPORT2
jpayne@69 454 umsg_setLocale(UMessageFormat *fmt,
jpayne@69 455 const char* locale);
jpayne@69 456
jpayne@69 457 /**
jpayne@69 458 * Gets the locale. This locale is used for fetching default number or date
jpayne@69 459 * format information.
jpayne@69 460 * @param fmt The formatter to querry
jpayne@69 461 * @return the locale.
jpayne@69 462 * @stable ICU 2.0
jpayne@69 463 */
jpayne@69 464 U_STABLE const char* U_EXPORT2
jpayne@69 465 umsg_getLocale(const UMessageFormat *fmt);
jpayne@69 466
jpayne@69 467 /**
jpayne@69 468 * Sets the pattern.
jpayne@69 469 * @param fmt The formatter to use
jpayne@69 470 * @param pattern The pattern to be applied.
jpayne@69 471 * @param patternLength Length of the pattern to use
jpayne@69 472 * @param parseError Struct to receive information on position
jpayne@69 473 * of error if an error is encountered.Can be NULL.
jpayne@69 474 * @param status Output param set to success/failure code on
jpayne@69 475 * exit. If the pattern is invalid, this will be
jpayne@69 476 * set to a failure result.
jpayne@69 477 * @stable ICU 2.0
jpayne@69 478 */
jpayne@69 479 U_STABLE void U_EXPORT2
jpayne@69 480 umsg_applyPattern( UMessageFormat *fmt,
jpayne@69 481 const UChar* pattern,
jpayne@69 482 int32_t patternLength,
jpayne@69 483 UParseError* parseError,
jpayne@69 484 UErrorCode* status);
jpayne@69 485
jpayne@69 486 /**
jpayne@69 487 * Gets the pattern.
jpayne@69 488 * @param fmt The formatter to use
jpayne@69 489 * @param result A pointer to a buffer to receive the pattern.
jpayne@69 490 * @param resultLength The maximum size of result.
jpayne@69 491 * @param status Output param set to success/failure code on
jpayne@69 492 * exit. If the pattern is invalid, this will be
jpayne@69 493 * set to a failure result.
jpayne@69 494 * @return the pattern of the format
jpayne@69 495 * @stable ICU 2.0
jpayne@69 496 */
jpayne@69 497 U_STABLE int32_t U_EXPORT2
jpayne@69 498 umsg_toPattern(const UMessageFormat *fmt,
jpayne@69 499 UChar* result,
jpayne@69 500 int32_t resultLength,
jpayne@69 501 UErrorCode* status);
jpayne@69 502
jpayne@69 503 /**
jpayne@69 504 * Format a message for a locale.
jpayne@69 505 * This function may perform re-ordering of the arguments depending on the
jpayne@69 506 * locale. For all numeric arguments, double is assumed unless the type is
jpayne@69 507 * explicitly integer. All choice format arguments must be of type double.
jpayne@69 508 * @param fmt The formatter to use
jpayne@69 509 * @param result A pointer to a buffer to receive the formatted message.
jpayne@69 510 * @param resultLength The maximum size of result.
jpayne@69 511 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 512 * @param ... A variable-length argument list containing the arguments
jpayne@69 513 * specified in pattern.
jpayne@69 514 * @return The total buffer size needed; if greater than resultLength,
jpayne@69 515 * the output was truncated.
jpayne@69 516 * @stable ICU 2.0
jpayne@69 517 */
jpayne@69 518 U_STABLE int32_t U_EXPORT2
jpayne@69 519 umsg_format( const UMessageFormat *fmt,
jpayne@69 520 UChar *result,
jpayne@69 521 int32_t resultLength,
jpayne@69 522 UErrorCode *status,
jpayne@69 523 ...);
jpayne@69 524
jpayne@69 525 /**
jpayne@69 526 * Format a message for a locale.
jpayne@69 527 * This function may perform re-ordering of the arguments depending on the
jpayne@69 528 * locale. For all numeric arguments, double is assumed unless the type is
jpayne@69 529 * explicitly integer. All choice format arguments must be of type double.
jpayne@69 530 * @param fmt The formatter to use
jpayne@69 531 * @param result A pointer to a buffer to receive the formatted message.
jpayne@69 532 * @param resultLength The maximum size of result.
jpayne@69 533 * @param ap A variable-length argument list containing the arguments
jpayne@69 534 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 535 * specified in pattern.
jpayne@69 536 * @return The total buffer size needed; if greater than resultLength,
jpayne@69 537 * the output was truncated.
jpayne@69 538 * @stable ICU 2.0
jpayne@69 539 */
jpayne@69 540 U_STABLE int32_t U_EXPORT2
jpayne@69 541 umsg_vformat( const UMessageFormat *fmt,
jpayne@69 542 UChar *result,
jpayne@69 543 int32_t resultLength,
jpayne@69 544 va_list ap,
jpayne@69 545 UErrorCode *status);
jpayne@69 546
jpayne@69 547 /**
jpayne@69 548 * Parse a message.
jpayne@69 549 * For numeric arguments, this function will always use doubles. Integer types
jpayne@69 550 * should not be passed.
jpayne@69 551 * This function is not able to parse all output from {@link #umsg_format }.
jpayne@69 552 * @param fmt The formatter to use
jpayne@69 553 * @param source The text to parse.
jpayne@69 554 * @param sourceLength The length of source, or -1 if null-terminated.
jpayne@69 555 * @param count Output param to receive number of elements returned.
jpayne@69 556 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 557 * @param ... A variable-length argument list containing the arguments
jpayne@69 558 * specified in pattern.
jpayne@69 559 * @stable ICU 2.0
jpayne@69 560 */
jpayne@69 561 U_STABLE void U_EXPORT2
jpayne@69 562 umsg_parse( const UMessageFormat *fmt,
jpayne@69 563 const UChar *source,
jpayne@69 564 int32_t sourceLength,
jpayne@69 565 int32_t *count,
jpayne@69 566 UErrorCode *status,
jpayne@69 567 ...);
jpayne@69 568
jpayne@69 569 /**
jpayne@69 570 * Parse a message.
jpayne@69 571 * For numeric arguments, this function will always use doubles. Integer types
jpayne@69 572 * should not be passed.
jpayne@69 573 * This function is not able to parse all output from {@link #umsg_format }.
jpayne@69 574 * @param fmt The formatter to use
jpayne@69 575 * @param source The text to parse.
jpayne@69 576 * @param sourceLength The length of source, or -1 if null-terminated.
jpayne@69 577 * @param count Output param to receive number of elements returned.
jpayne@69 578 * @param ap A variable-length argument list containing the arguments
jpayne@69 579 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 580 * specified in pattern.
jpayne@69 581 * @see u_formatMessage
jpayne@69 582 * @stable ICU 2.0
jpayne@69 583 */
jpayne@69 584 U_STABLE void U_EXPORT2
jpayne@69 585 umsg_vparse(const UMessageFormat *fmt,
jpayne@69 586 const UChar *source,
jpayne@69 587 int32_t sourceLength,
jpayne@69 588 int32_t *count,
jpayne@69 589 va_list ap,
jpayne@69 590 UErrorCode *status);
jpayne@69 591
jpayne@69 592
jpayne@69 593 /**
jpayne@69 594 * Convert an 'apostrophe-friendly' pattern into a standard
jpayne@69 595 * pattern. Standard patterns treat all apostrophes as
jpayne@69 596 * quotes, which is problematic in some languages, e.g.
jpayne@69 597 * French, where apostrophe is commonly used. This utility
jpayne@69 598 * assumes that only an unpaired apostrophe immediately before
jpayne@69 599 * a brace is a true quote. Other unpaired apostrophes are paired,
jpayne@69 600 * and the resulting standard pattern string is returned.
jpayne@69 601 *
jpayne@69 602 * <p><b>Note</b> it is not guaranteed that the returned pattern
jpayne@69 603 * is indeed a valid pattern. The only effect is to convert
jpayne@69 604 * between patterns having different quoting semantics.
jpayne@69 605 *
jpayne@69 606 * @param pattern the 'apostrophe-friendly' patttern to convert
jpayne@69 607 * @param patternLength the length of pattern, or -1 if unknown and pattern is null-terminated
jpayne@69 608 * @param dest the buffer for the result, or NULL if preflight only
jpayne@69 609 * @param destCapacity the length of the buffer, or 0 if preflighting
jpayne@69 610 * @param ec the error code
jpayne@69 611 * @return the length of the resulting text, not including trailing null
jpayne@69 612 * if buffer has room for the trailing null, it is provided, otherwise
jpayne@69 613 * not
jpayne@69 614 * @stable ICU 3.4
jpayne@69 615 */
jpayne@69 616 U_STABLE int32_t U_EXPORT2
jpayne@69 617 umsg_autoQuoteApostrophe(const UChar* pattern,
jpayne@69 618 int32_t patternLength,
jpayne@69 619 UChar* dest,
jpayne@69 620 int32_t destCapacity,
jpayne@69 621 UErrorCode* ec);
jpayne@69 622
jpayne@69 623 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 624
jpayne@69 625 #endif