Main Page   Class Hierarchy   Compound List   File List   Header Files   Sources   Compound Members   File Members  

umsg.h File Reference

Message Format C API. More...


Functions

U_CAPI 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...

U_CAPI 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...

U_CAPI void u_parseMessage ( const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UErrorCode *status, ...)
Parse a message. More...

U_CAPI 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...


Detailed Description

Message Format C API.

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:

 .    UChar *result, *tzID, *str;
 .    UChar pattern[100];
 .    t_int32 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
 
Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.

Example 2:

 .    UChar* str;
 .    UErrorCode status = U_ZERO_ERROR;
 .    UChar *result;
 .    UChar pattern[100];
 .    t_int32 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:

 .      {optional item}
 .      (group that may be repeated)*
  
Do not confuse optional items with items inside quotes braces, such as this: "{". Quoted braces are literals.
 .      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
 
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.

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!

 .   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}
 
and so on.

Definition in file umsg.h.


Function Documentation

U_CAPI 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:
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.
Returns:
The total buffer size needed; if greater than resultLength, the output was truncated.
See also:
u_parseMessage()
Draft:
should this just be usprintf?

U_CAPI 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:
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.
Returns:
The total buffer size needed; if greater than resultLength, the output was truncated.
See also:
u_parseMessage()

U_CAPI 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 \Ref{u_formatMessage}.

Parameters:
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.
See also:
u_formatMessage()
Draft:

U_CAPI 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 \Ref{u_formatMessage}.

Parameters:
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.
See also:
u_formatMessage()

Generated at Mon Jun 5 12:52:59 2000 for ICU1.5 by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999