#include "unicode/utypes.h"
#include "unicode/uloc.h"
#include "unicode/parseerr.h"
#include <stdarg.h>
Go to the source code of this file.
Typedefs | |
typedef void * | UMessageFormat |
The message format object. | |
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. | |
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. | |
void | u_parseMessage (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UErrorCode *status,...) |
Parse a message. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
void | umsg_close (UMessageFormat *format) |
Close a UMessageFormat. | |
UMessageFormat | umsg_clone (const UMessageFormat *fmt, UErrorCode *status) |
Open a copy of a UMessageFormat. | |
void | umsg_setLocale (UMessageFormat *fmt, const char *locale) |
Sets the locale. | |
const char * | umsg_getLocale (const UMessageFormat *fmt) |
Gets the locale. | |
void | umsg_applyPattern (UMessageFormat *fmt, const UChar *pattern, int32_t patternLength, UParseError *parseError, UErrorCode *status) |
Sets the pattern. | |
int32_t | umsg_toPattern (const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status) |
Gets the pattern. | |
int32_t | umsg_format (const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status,...) |
Format a message for a locale. | |
int32_t | umsg_vformat (const UMessageFormat *fmt, UChar *result, int32_t resultLength, va_list ap, UErrorCode *status) |
Format a message for a locale. | |
void | umsg_parse (const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, UErrorCode *status,...) |
Parse a message. | |
void | umsg_vparse (const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, va_list ap, UErrorCode *status) |
Parse a message. | |
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. |
Provides means to produce concatenated messages in language-neutral way. Use this for all concatenations that show up to end users.
Takes a set of objects, formats them, then inserts the formatted strings into the pattern at the appropriate places.
Here are some examples of usage: Example 1:
Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.UChar *result, *tzID, *str; UChar pattern[100]; int32_t resultLengthOut, resultlength; UCalendar *cal; UDate d1; UDateFormat *def1; UErrorCode status = U_ZERO_ERROR; 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); if(status==U_BUFFER_OVERFLOW_ERROR){ 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
Example 2:
UChar* str; UErrorCode status = U_ZERO_ERROR; 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); if(status==U_BUFFER_OVERFLOW_ERROR){ 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.
The pattern is of the following form. Legend:
Do not confuse optional items with items inside quotes braces, such as this: "{". Quoted braces are literals.{optional item} (group that may be repeated)*
If there is no elementFormat, then the argument must be a string, which is substituted. If there is no dateTimeStyle or numberStyle, then the default format is used (e.g. NumberFormat.getInstance(), DateFormat.getDefaultTime() or DateFormat.getDefaultDate(). For a ChoiceFormat, the pattern must always be specified, since there is no default.messageFormatPattern := string ( "{" messageFormatElement "}" string )* messageFormatElement := argument { "," elementFormat } elementFormat := "time" { "," datetimeStyle } | "date" { "," datetimeStyle } | "number" { "," numberStyle } | "choice" "," choiceStyle datetimeStyle := "short" | "medium" | "long" | "full" | dateFormatPattern numberStyle := "currency" | "percent" | "integer" | numberFormatPattern choiceStyle := choiceFormatPattern
In strings, single quotes can be used to quote the "{" sign if necessary. A real single quote is represented by ''. Inside a messageFormatElement, quotes are [not] removed. For example, {1,number,$'#',##} will produce a number format with the pound-sign quoted, with a result such as: "$#31,45".
If a pattern is used, then unquoted braces in the pattern, if any, must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab {0'}' de" and "ab } de" are not.
The argument is a number from 0 to 9, which corresponds to the arguments presented in an array to be formatted.
It is ok to have unused arguments in the array. With missing arguments or arguments that are not of the right class for the specified format, a failing UErrorCode result is set.
[Note:] As we see above, the string produced by a choice Format in MessageFormat is treated specially; occurances of '{' are used to indicated subformats.
[Note:] Formats are numbered by order of variable in the string. This is [not] the same as the argument numbering!
and so on.For example: with "abc{2}def{3}ghi{0}...", format0 affects the first variable {2} format1 affects the second variable {3} format2 affects the second variable {0}
Definition in file umsg.h.
typedef void* UMessageFormat |
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.
locale | The locale for which the message will be formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
result | A pointer to a buffer to receive the formatted message. | |
resultLength | The maximum size of result. | |
status | A pointer to an UErrorCode to receive any errors | |
... | A variable-length argument list containing the arguments specified in pattern. |
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.
locale | The locale for which the message will be formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
result | A pointer to a buffer to receive the formatted message. | |
resultLength | The maximum size of result. | |
status | A pointer to an UErrorCode to receive any errors | |
... | A variable-length argument list containing the arguments specified in pattern. | |
parseError | A pointer to UParseError to receive information about errors occurred during parsing. |
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.
locale | The locale for which the message is formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
source | The text to parse. | |
sourceLength | The length of source, or -1 if null-terminated. | |
status | A pointer to an UErrorCode to receive any errors | |
... | A variable-length argument list containing the arguments specified in pattern. |
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.
locale | The locale for which the message is formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
source | The text to parse. | |
sourceLength | The length of source, or -1 if null-terminated. | |
parseError | A pointer to UParseError to receive information about errors occurred during parsing. | |
status | A pointer to an UErrorCode to receive any errors | |
... | A variable-length argument list containing the arguments specified in pattern. |
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.
locale | The locale for which the message will be formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
result | A pointer to a buffer to receive the formatted message. | |
resultLength | The maximum size of result. | |
ap | A variable-length argument list containing the arguments specified | |
status | A pointer to an UErrorCode to receive any errors in pattern. |
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.
locale | The locale for which the message will be formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
result | A pointer to a buffer to receive the formatted message. | |
resultLength | The maximum size of result. | |
parseError | A pointer to UParseError to receive information about errors occurred during parsing. | |
ap | A variable-length argument list containing the arguments specified | |
status | A pointer to an UErrorCode to receive any errors in pattern. |
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.
locale | The locale for which the message is formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
source | The text to parse. | |
sourceLength | The length of source, or -1 if null-terminated. | |
ap | A variable-length argument list containing the arguments | |
status | A pointer to an UErrorCode to receive any errors specified in pattern. |
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.
locale | The locale for which the message is formatted | |
pattern | The pattern specifying the message's format | |
patternLength | The length of pattern | |
source | The text to parse. | |
sourceLength | The length of source, or -1 if null-terminated. | |
ap | A variable-length argument list containing the arguments | |
parseError | A pointer to UParseError to receive information about errors occurred during parsing. | |
status | A pointer to an UErrorCode to receive any errors specified in pattern. |
void umsg_applyPattern | ( | UMessageFormat * | fmt, | |
const UChar * | pattern, | |||
int32_t | patternLength, | |||
UParseError * | parseError, | |||
UErrorCode * | status | |||
) |
Sets the pattern.
fmt | The formatter to use | |
pattern | The pattern to be applied. | |
patternLength | Length of the pattern to use | |
parseError | Struct to receive information on position of error if an error is encountered.Can be NULL. | |
status | Output param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result. |
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.
pattern | the 'apostrophe-friendly' patttern to convert | |
patternLength | the length of pattern, or -1 if unknown and pattern is null-terminated | |
dest | the buffer for the result, or NULL if preflight only | |
destCapacity | the length of the buffer, or 0 if preflighting | |
ec | the error code |
UMessageFormat umsg_clone | ( | const UMessageFormat * | fmt, | |
UErrorCode * | status | |||
) |
Open a copy of a UMessageFormat.
This function performs a deep copy.
fmt | The formatter to copy | |
status | A pointer to an UErrorCode to receive any errors. |
void umsg_close | ( | UMessageFormat * | format | ) |
Close a UMessageFormat.
Once closed, a UMessageFormat may no longer be used.
format | The formatter to close. |
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.
fmt | The formatter to use | |
result | A pointer to a buffer to receive the formatted message. | |
resultLength | The maximum size of result. | |
status | A pointer to an UErrorCode to receive any errors | |
... | A variable-length argument list containing the arguments specified in pattern. |
const char* umsg_getLocale | ( | const UMessageFormat * | fmt | ) |
Gets the locale.
This locale is used for fetching default number or date format information.
fmt | The formatter to querry |
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.
pattern | A pattern specifying the format to use. | |
patternLength | Length of the pattern to use | |
locale | The locale for which the messages are formatted. | |
parseError | A pointer to UParseError struct to receive any errors occured during parsing. Can be NULL. | |
status | A pointer to an UErrorCode to receive any errors. |
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.
fmt | The formatter to use | |
source | The text to parse. | |
sourceLength | The length of source, or -1 if null-terminated. | |
count | Output param to receive number of elements returned. | |
status | A pointer to an UErrorCode to receive any errors | |
... | A variable-length argument list containing the arguments specified in pattern. |
void umsg_setLocale | ( | UMessageFormat * | fmt, | |
const char * | locale | |||
) |
Sets the locale.
This locale is used for fetching default number or date format information.
fmt | The formatter to set | |
locale | The locale the formatter should use. |
int32_t umsg_toPattern | ( | const UMessageFormat * | fmt, | |
UChar * | result, | |||
int32_t | resultLength, | |||
UErrorCode * | status | |||
) |
Gets the pattern.
fmt | The formatter to use | |
result | A pointer to a buffer to receive the pattern. | |
resultLength | The maximum size of result. | |
status | Output param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result. |
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.
fmt | The formatter to use | |
result | A pointer to a buffer to receive the formatted message. | |
resultLength | The maximum size of result. | |
ap | A variable-length argument list containing the arguments | |
status | A pointer to an UErrorCode to receive any errors specified in pattern. |
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.
fmt | The formatter to use | |
source | The text to parse. | |
sourceLength | The length of source, or -1 if null-terminated. | |
count | Output param to receive number of elements returned. | |
ap | A variable-length argument list containing the arguments | |
status | A pointer to an UErrorCode to receive any errors specified in pattern. |