ICU 53.1  53.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Namespaces | Typedefs | Functions
umsg.h File Reference

C API: MessageFormat. More...

#include "unicode/utypes.h"
#include "unicode/localpointer.h"
#include "unicode/uloc.h"
#include "unicode/parseerr.h"
#include <stdarg.h>

Go to the source code of this file.

Namespaces

 icu
 File coll.h.
 

Typedefs

typedef void * UMessageFormat
 The message format object. More...
 

Functions

int32_t u_formatMessage (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, UErrorCode *status,...)
 Format a message for a locale. More...
 
int32_t u_vformatMessage (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, va_list ap, UErrorCode *status)
 Format a message for a locale. More...
 
void u_parseMessage (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UErrorCode *status,...)
 Parse a message. More...
 
void u_vparseMessage (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, va_list ap, UErrorCode *status)
 Parse a message. More...
 
int32_t u_formatMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, UParseError *parseError, UErrorCode *status,...)
 Format a message for a locale. More...
 
int32_t u_vformatMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, UParseError *parseError, va_list ap, UErrorCode *status)
 Format a message for a locale. More...
 
void u_parseMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UParseError *parseError, UErrorCode *status,...)
 Parse a message. More...
 
void u_vparseMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, va_list ap, UParseError *parseError, UErrorCode *status)
 Parse a message. More...
 
UMessageFormatumsg_open (const UChar *pattern, int32_t patternLength, const char *locale, UParseError *parseError, UErrorCode *status)
 Open a message formatter with given pattern and for the given locale. More...
 
void umsg_close (UMessageFormat *format)
 Close a UMessageFormat. More...
 
UMessageFormat umsg_clone (const UMessageFormat *fmt, UErrorCode *status)
 Open a copy of a UMessageFormat. More...
 
void umsg_setLocale (UMessageFormat *fmt, const char *locale)
 Sets the locale. More...
 
const char * umsg_getLocale (const UMessageFormat *fmt)
 Gets the locale. More...
 
void umsg_applyPattern (UMessageFormat *fmt, const UChar *pattern, int32_t patternLength, UParseError *parseError, UErrorCode *status)
 Sets the pattern. More...
 
int32_t umsg_toPattern (const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status)
 Gets the pattern. More...
 
int32_t umsg_format (const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status,...)
 Format a message for a locale. More...
 
int32_t umsg_vformat (const UMessageFormat *fmt, UChar *result, int32_t resultLength, va_list ap, UErrorCode *status)
 Format a message for a locale. More...
 
void umsg_parse (const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, UErrorCode *status,...)
 Parse a message. More...
 
void umsg_vparse (const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, va_list ap, UErrorCode *status)
 Parse a message. More...
 
int32_t umsg_autoQuoteApostrophe (const UChar *pattern, int32_t patternLength, UChar *dest, int32_t destCapacity, UErrorCode *ec)
 Convert an 'apostrophe-friendly' pattern into a standard pattern. More...
 

Detailed Description

C API: MessageFormat.

MessageFormat C API

MessageFormat prepares strings for display to users, with optional arguments (variables/placeholders). The arguments can occur in any order, which is necessary for translation into languages with different grammars.

The opaque UMessageFormat type is a thin C wrapper around a C++ MessageFormat. It is constructed from a pattern string with arguments in {curly braces} which will be replaced by formatted values.

Currently, the C API supports only numbered arguments.

For details about the pattern syntax and behavior, especially about the ASCII apostrophe vs. the real apostrophe (single quote) character ’ (U+2019), see the C++ MessageFormat class documentation.

Here are some examples of C API usage: Example 1:

UChar *result, *tzID, *str;
UChar pattern[100];
int32_t resultLengthOut, resultlength;
UCalendar *cal;
UDate d1;
str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
u_uastrcpy(str, "disturbance in force");
tzID=(UChar*)malloc(sizeof(UChar) * 4);
u_uastrcpy(tzID, "PST");
cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
d1=ucal_getMillis(cal, &status);
u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet {2,number,integer}");
resultlength=0;
resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, d1, str, 7);
status=U_ZERO_ERROR;
resultlength=resultLengthOut+1;
result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, d1, str, 7);
}
printf("%s\n", austrdup(result) );//austrdup( a function used to convert UChar* to char*)
//output>: "On March 18, 1999, there was a disturbance in force on planet 7

Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.

Example 2:

UChar* str;
UChar *result;
UChar pattern[100];
int32_t resultlength, resultLengthOut, i;
double testArgs= { 100.0, 1.0, 0.0};
str=(UChar*)malloc(sizeof(UChar) * 10);
u_uastrcpy(str, "MyDisk");
u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one file|1<{0,number,integer} files}");
for(i=0; i<3; i++){
resultlength=0;
resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str);
status=U_ZERO_ERROR;
resultlength=resultLengthOut+1;
result=(UChar*)malloc(sizeof(UChar) * resultlength);
u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, testArgs[i], str);
}
printf("%s\n", austrdup(result) ); //austrdup( a function used to convert UChar* to char*)
free(result);
}
// output, with different testArgs:
// output: The disk "MyDisk" contains 100 files.
// output: The disk "MyDisk" contains one file.
// output: The disk "MyDisk" contains no files.

Example 3:

UChar* str;
UChar* str1;
UChar *result;
UChar pattern[100];
UChar expected[100];
int32_t resultlength,resultLengthOut;
str=(UChar*)malloc(sizeof(UChar) * 25);
u_uastrcpy(str, "Kirti");
str1=(UChar*)malloc(sizeof(UChar) * 25);
u_uastrcpy(str1, "female");
log_verbose("Testing message format with Select test #1\n:");
u_uastrcpy(pattern, "{0} est {1, select, female {all\\u00E9e} other {all\\u00E9}} \\u00E0 Paris.");
u_uastrcpy(expected, "Kirti est all\\u00E9e \\u00E0 Paris.");
resultlength=0;
resultLengthOut=u_formatMessage( "fr", pattern, u_strlen(pattern), NULL, resultlength, &status, str , str1);
{
status=U_ZERO_ERROR;
resultlength=resultLengthOut+1;
result=(UChar*)malloc(sizeof(UChar) * resultlength);
u_formatMessage( "fr", pattern, u_strlen(pattern), result, resultlength, &status, str , str1);
if(u_strcmp(result, expected)==0)
log_verbose("PASS: MessagFormat successful on Select test#1\n");
else{
log_err("FAIL: Error in MessageFormat on Select test#1\n GOT %s EXPECTED %s\n", austrdup(result),
austrdup(expected) );
}
free(result);
}

Definition in file umsg.h.

Typedef Documentation

typedef void* UMessageFormat

The message format object.

Stable:
ICU 2.0

Definition at line 382 of file umsg.h.

Function Documentation

int32_t u_formatMessage ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
UChar result,
int32_t  resultLength,
UErrorCode status,
  ... 
)

Format a message for a locale.

This function may perform re-ordering of the arguments depending on the locale. For all numeric arguments, double is assumed unless the type is explicitly integer. All choice format arguments must be of type double.

Parameters
localeThe locale for which the message will be formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
resultA pointer to a buffer to receive the formatted message.
resultLengthThe maximum size of result.
statusA pointer to an UErrorCode to receive any errors
...A variable-length argument list containing the arguments specified in pattern.
Returns
The total buffer size needed; if greater than resultLength, the output was truncated.
See Also
u_parseMessage
Stable:
ICU 2.0
int32_t u_formatMessageWithError ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
UChar result,
int32_t  resultLength,
UParseError parseError,
UErrorCode status,
  ... 
)

Format a message for a locale.

This function may perform re-ordering of the arguments depending on the locale. For all numeric arguments, double is assumed unless the type is explicitly integer. All choice format arguments must be of type double.

Parameters
localeThe locale for which the message will be formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
resultA pointer to a buffer to receive the formatted message.
resultLengthThe maximum size of result.
statusA pointer to an UErrorCode to receive any errors
...A variable-length argument list containing the arguments specified in pattern.
parseErrorA pointer to UParseError to receive information about errors occurred during parsing.
Returns
The total buffer size needed; if greater than resultLength, the output was truncated.
See Also
u_parseMessage
Stable:
ICU 2.0
void u_parseMessage ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
const UChar source,
int32_t  sourceLength,
UErrorCode status,
  ... 
)

Parse a message.

For numeric arguments, this function will always use doubles. Integer types should not be passed. This function is not able to parse all output from u_formatMessage.

Parameters
localeThe locale for which the message is formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
sourceThe text to parse.
sourceLengthThe length of source, or -1 if null-terminated.
statusA pointer to an UErrorCode to receive any errors
...A variable-length argument list containing the arguments specified in pattern.
See Also
u_formatMessage
Stable:
ICU 2.0
void u_parseMessageWithError ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
const UChar source,
int32_t  sourceLength,
UParseError parseError,
UErrorCode status,
  ... 
)

Parse a message.

For numeric arguments, this function will always use doubles. Integer types should not be passed. This function is not able to parse all output from u_formatMessage.

Parameters
localeThe locale for which the message is formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
sourceThe text to parse.
sourceLengthThe length of source, or -1 if null-terminated.
parseErrorA pointer to UParseError to receive information about errors occurred during parsing.
statusA pointer to an UErrorCode to receive any errors
...A variable-length argument list containing the arguments specified in pattern.
See Also
u_formatMessage
Stable:
ICU 2.0
int32_t u_vformatMessage ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
UChar result,
int32_t  resultLength,
va_list  ap,
UErrorCode status 
)

Format a message for a locale.

This function may perform re-ordering of the arguments depending on the locale. For all numeric arguments, double is assumed unless the type is explicitly integer. All choice format arguments must be of type double.

Parameters
localeThe locale for which the message will be formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
resultA pointer to a buffer to receive the formatted message.
resultLengthThe maximum size of result.
apA variable-length argument list containing the arguments specified
statusA pointer to an UErrorCode to receive any errors in pattern.
Returns
The total buffer size needed; if greater than resultLength, the output was truncated.
See Also
u_parseMessage
Stable:
ICU 2.0
int32_t u_vformatMessageWithError ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
UChar result,
int32_t  resultLength,
UParseError parseError,
va_list  ap,
UErrorCode status 
)

Format a message for a locale.

This function may perform re-ordering of the arguments depending on the locale. For all numeric arguments, double is assumed unless the type is explicitly integer. All choice format arguments must be of type double.

Parameters
localeThe locale for which the message will be formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
resultA pointer to a buffer to receive the formatted message.
resultLengthThe maximum size of result.
parseErrorA pointer to UParseError to receive information about errors occurred during parsing.
apA variable-length argument list containing the arguments specified
statusA pointer to an UErrorCode to receive any errors in pattern.
Returns
The total buffer size needed; if greater than resultLength, the output was truncated.
Stable:
ICU 2.0
void u_vparseMessage ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
const UChar source,
int32_t  sourceLength,
va_list  ap,
UErrorCode status 
)

Parse a message.

For numeric arguments, this function will always use doubles. Integer types should not be passed. This function is not able to parse all output from u_formatMessage.

Parameters
localeThe locale for which the message is formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
sourceThe text to parse.
sourceLengthThe length of source, or -1 if null-terminated.
apA variable-length argument list containing the arguments
statusA pointer to an UErrorCode to receive any errors specified in pattern.
See Also
u_formatMessage
Stable:
ICU 2.0
void u_vparseMessageWithError ( const char *  locale,
const UChar pattern,
int32_t  patternLength,
const UChar source,
int32_t  sourceLength,
va_list  ap,
UParseError parseError,
UErrorCode status 
)

Parse a message.

For numeric arguments, this function will always use doubles. Integer types should not be passed. This function is not able to parse all output from u_formatMessage.

Parameters
localeThe locale for which the message is formatted
patternThe pattern specifying the message's format
patternLengthThe length of pattern
sourceThe text to parse.
sourceLengthThe length of source, or -1 if null-terminated.
apA variable-length argument list containing the arguments
parseErrorA pointer to UParseError to receive information about errors occurred during parsing.
statusA pointer to an UErrorCode to receive any errors specified in pattern.
See Also
u_formatMessage
Stable:
ICU 2.0
void umsg_applyPattern ( UMessageFormat fmt,
const UChar pattern,
int32_t  patternLength,
UParseError parseError,
UErrorCode status 
)

Sets the pattern.

Parameters
fmtThe formatter to use
patternThe pattern to be applied.
patternLengthLength of the pattern to use
parseErrorStruct to receive information on position of error if an error is encountered.Can be NULL.
statusOutput param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.
Stable:
ICU 2.0
int32_t umsg_autoQuoteApostrophe ( const UChar pattern,
int32_t  patternLength,
UChar dest,
int32_t  destCapacity,
UErrorCode ec 
)

Convert an 'apostrophe-friendly' pattern into a standard pattern.

Standard patterns treat all apostrophes as quotes, which is problematic in some languages, e.g. French, where apostrophe is commonly used. This utility assumes that only an unpaired apostrophe immediately before a brace is a true quote. Other unpaired apostrophes are paired, and the resulting standard pattern string is returned.

Note it is not guaranteed that the returned pattern is indeed a valid pattern. The only effect is to convert between patterns having different quoting semantics.

Parameters
patternthe 'apostrophe-friendly' patttern to convert
patternLengththe length of pattern, or -1 if unknown and pattern is null-terminated
destthe buffer for the result, or NULL if preflight only
destCapacitythe length of the buffer, or 0 if preflighting
ecthe error code
Returns
the length of the resulting text, not including trailing null if buffer has room for the trailing null, it is provided, otherwise not
Stable:
ICU 3.4
UMessageFormat umsg_clone ( const UMessageFormat fmt,
UErrorCode status 
)

Open a copy of a UMessageFormat.

This function performs a deep copy.

Parameters
fmtThe formatter to copy
statusA pointer to an UErrorCode to receive any errors.
Returns
A pointer to a UDateFormat identical to fmt.
Stable:
ICU 2.0
void umsg_close ( UMessageFormat format)

Close a UMessageFormat.

Once closed, a UMessageFormat may no longer be used.

Parameters
formatThe formatter to close.
Stable:
ICU 2.0
int32_t umsg_format ( const UMessageFormat fmt,
UChar result,
int32_t  resultLength,
UErrorCode status,
  ... 
)

Format a message for a locale.

This function may perform re-ordering of the arguments depending on the locale. For all numeric arguments, double is assumed unless the type is explicitly integer. All choice format arguments must be of type double.

Parameters
fmtThe formatter to use
resultA pointer to a buffer to receive the formatted message.
resultLengthThe maximum size of result.
statusA pointer to an UErrorCode to receive any errors
...A variable-length argument list containing the arguments specified in pattern.
Returns
The total buffer size needed; if greater than resultLength, the output was truncated.
Stable:
ICU 2.0
const char* umsg_getLocale ( const UMessageFormat fmt)

Gets the locale.

This locale is used for fetching default number or date format information.

Parameters
fmtThe formatter to querry
Returns
the locale.
Stable:
ICU 2.0
UMessageFormat* umsg_open ( const UChar pattern,
int32_t  patternLength,
const char *  locale,
UParseError parseError,
UErrorCode status 
)

Open a message formatter with given pattern and for the given locale.

Parameters
patternA pattern specifying the format to use.
patternLengthLength of the pattern to use
localeThe locale for which the messages are formatted.
parseErrorA pointer to UParseError struct to receive any errors occured during parsing. Can be NULL.
statusA pointer to an UErrorCode to receive any errors.
Returns
A pointer to a UMessageFormat to use for formatting messages, or 0 if an error occurred.
Stable:
ICU 2.0
void umsg_parse ( const UMessageFormat fmt,
const UChar source,
int32_t  sourceLength,
int32_t *  count,
UErrorCode status,
  ... 
)

Parse a message.

For numeric arguments, this function will always use doubles. Integer types should not be passed. This function is not able to parse all output from umsg_format.

Parameters
fmtThe formatter to use
sourceThe text to parse.
sourceLengthThe length of source, or -1 if null-terminated.
countOutput param to receive number of elements returned.
statusA pointer to an UErrorCode to receive any errors
...A variable-length argument list containing the arguments specified in pattern.
Stable:
ICU 2.0
void umsg_setLocale ( UMessageFormat fmt,
const char *  locale 
)

Sets the locale.

This locale is used for fetching default number or date format information.

Parameters
fmtThe formatter to set
localeThe locale the formatter should use.
Stable:
ICU 2.0
int32_t umsg_toPattern ( const UMessageFormat fmt,
UChar result,
int32_t  resultLength,
UErrorCode status 
)

Gets the pattern.

Parameters
fmtThe formatter to use
resultA pointer to a buffer to receive the pattern.
resultLengthThe maximum size of result.
statusOutput param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.
Returns
the pattern of the format
Stable:
ICU 2.0
int32_t umsg_vformat ( const UMessageFormat fmt,
UChar result,
int32_t  resultLength,
va_list  ap,
UErrorCode status 
)

Format a message for a locale.

This function may perform re-ordering of the arguments depending on the locale. For all numeric arguments, double is assumed unless the type is explicitly integer. All choice format arguments must be of type double.

Parameters
fmtThe formatter to use
resultA pointer to a buffer to receive the formatted message.
resultLengthThe maximum size of result.
apA variable-length argument list containing the arguments
statusA pointer to an UErrorCode to receive any errors specified in pattern.
Returns
The total buffer size needed; if greater than resultLength, the output was truncated.
Stable:
ICU 2.0
void umsg_vparse ( const UMessageFormat fmt,
const UChar source,
int32_t  sourceLength,
int32_t *  count,
va_list  ap,
UErrorCode status 
)

Parse a message.

For numeric arguments, this function will always use doubles. Integer types should not be passed. This function is not able to parse all output from umsg_format.

Parameters
fmtThe formatter to use
sourceThe text to parse.
sourceLengthThe length of source, or -1 if null-terminated.
countOutput param to receive number of elements returned.
apA variable-length argument list containing the arguments
statusA pointer to an UErrorCode to receive any errors specified in pattern.
See Also
u_formatMessage
Stable:
ICU 2.0