Main Page   Class Hierarchy   Alphabetical List   Data Structures   File List   Data Fields   Globals   Related Pages  

umsg.h File Reference

C API: MessageFormat. More...

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

Go to the source code of this file.

Typedefs

typedef void * UMessageFormat

Functions

U_CAPI int32_t U_EXPORT2 u_formatMessage (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, UErrorCode *status,...)
 Format a message for a locale.

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

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

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

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

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

U_CAPI void U_EXPORT2 u_parseMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UParseError *error, UErrorCode *status,...)
 Parse a message.

U_CAPI void U_EXPORT2 u_vparseMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, va_list ap, UParseError *error, UErrorCode *status)
 Parse a message.

U_CAPI UMessageFormat *U_EXPORT2 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.

U_CAPI void U_EXPORT2 umsg_close (UMessageFormat *format)
 Close a UMessageFormat.

U_CAPI UMessageFormat U_EXPORT2 umsg_clone (const UMessageFormat *fmt, UErrorCode *status)
 Open a copy of a UMessageFormat.

U_CAPI void U_EXPORT2 umsg_setLocale (UMessageFormat *fmt, const char *locale)
 Sets the locale.

U_CAPI const char *U_EXPORT2 umsg_getLocale (UMessageFormat *fmt)
 Gets the locale.

U_CAPI void U_EXPORT2 umsg_applyPattern (UMessageFormat *fmt, const UChar *pattern, int32_t patternLength, UParseError *parseError, UErrorCode *status)
 Sets the pattern.

U_CAPI int32_t U_EXPORT2 umsg_toPattern (UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status)
 Gets the pattern.

U_CAPI int32_t U_EXPORT2 umsg_format (UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status,...)
 Format a message for a locale.

U_CAPI int32_t U_EXPORT2 umsg_vformat (UMessageFormat *fmt, UChar *result, int32_t resultLength, va_list ap, UErrorCode *status)
 Format a message for a locale.

U_CAPI void U_EXPORT2 umsg_parse (UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, UErrorCode *status,...)
 Parse a message.

U_CAPI void U_EXPORT2 umsg_vparse (UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, va_list ap, UErrorCode *status)
 Parse a message.


Detailed Description

C API: MessageFormat.

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];
     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
 
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];
     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:

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

Function Documentation

U_CAPI int32_t U_EXPORT2 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

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

U_CAPI void U_EXPORT2 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:
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

U_CAPI void U_EXPORT2 u_parseMessageWithError const char *    locale,
const UChar   pattern,
int32_t    patternLength,
const UChar   source,
int32_t    sourceLength,
UParseError   error,
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:
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.
See also:
u_formatMessage ICU 2.0

U_CAPI int32_t U_EXPORT2 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 int32_t U_EXPORT2 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:
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.
Returns:
The total buffer size needed; if greater than resultLength, the output was truncated.

U_CAPI void U_EXPORT2 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:
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

U_CAPI void U_EXPORT2 u_vparseMessageWithError const char *    locale,
const UChar   pattern,
int32_t    patternLength,
const UChar   source,
int32_t    sourceLength,
va_list    ap,
UParseError   error,
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:
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.
See also:
u_formatMessage ICU 2.0

U_CAPI void U_EXPORT2 umsg_applyPattern UMessageFormat *    fmt,
const UChar   pattern,
int32_t    patternLength,
UParseError   parseError,
UErrorCode   status
 

Sets the pattern.

Parameters:
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.

U_CAPI UMessageFormat U_EXPORT2 umsg_clone const UMessageFormat *    fmt,
UErrorCode   status
 

Open a copy of a UMessageFormat.

This function performs a deep copy.

Parameters:
fmt The formatter to copy
status A pointer to an UErrorCode to receive any errors.
Returns:
A pointer to a UDateFormat identical to fmt.

U_CAPI void U_EXPORT2 umsg_close UMessageFormat *    format
 

Close a UMessageFormat.

Once closed, a UMessageFormat may no longer be used.

Parameters:
fmt The formatter to close.

U_CAPI int32_t U_EXPORT2 umsg_format 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:
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.
Returns:
The total buffer size needed; if greater than resultLength, the output was truncated.

U_CAPI const char* U_EXPORT2 umsg_getLocale UMessageFormat *    fmt
 

Gets the locale.

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

Parameters:
The formatter to querry

U_CAPI UMessageFormat* U_EXPORT2 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:
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.
Returns:
A pointer to a UMessageFormat to use for formatting messages, or 0 if an error occurred. ICU 2.0

U_CAPI void U_EXPORT2 umsg_parse 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:
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.

U_CAPI void U_EXPORT2 umsg_setLocale UMessageFormat *    fmt,
const char *    locale
 

Sets the locale.

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

Parameters:
fmt The formatter to set
locale The locale the formatter should use.

U_CAPI int32_t U_EXPORT2 umsg_toPattern UMessageFormat *    fmt,
UChar   result,
int32_t    resultLength,
UErrorCode   status
 

Gets the pattern.

Parameters:
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.

U_CAPI int32_t U_EXPORT2 umsg_vformat 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:
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.
Returns:
The total buffer size needed; if greater than resultLength, the output was truncated.

U_CAPI void U_EXPORT2 umsg_vparse 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:
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.
See also:
u_formatMessage


Generated on Fri Mar 7 20:02:46 2003 for ICU 2.1 by doxygen1.3-rc3