Logo Search packages:      
Sourcecode: icu version File versions  Download package

umsg.h File Reference


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.

Example 3:

 
 UChar* str;
 UChar* str1;
 UErrorCode status = U_ZERO_ERROR;
 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);
 if(status==U_BUFFER_OVERFLOW_ERROR)
  {
      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);
 }

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
                      | "select" "," selectStyle

       datetimeStyle := "short"
                      | "medium"
                      | "long"
                      | "full"
                      | dateFormatPattern

       numberStyle :=   "currency"
                      | "percent"
                      | "integer"
                      | numberFormatPattern

       choiceStyle :=   choiceFormatPattern

       selectStyle :=   selectFormatPattern
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.

Warning:
The rules for using quotes within message format patterns unfortunately have shown to be somewhat confusing. In particular, it isn't always obvious to localizers whether single quotes need to be doubled or not. Make sure to inform localizers about the rules, and tell them (for example, by using comments in resource bundle source files) which strings will be processed by MessageFormat. Note that localizers may need to use single quotes in translated strings where the original version doesn't have them.
Note also that the simplest way to avoid the problem is to use the real apostrophe (single quote) character U+2019 (') for human-readable text, and to use the ASCII apostrophe (U+0027 ' ) only in program syntax, like quoting in MessageFormat. See the annotations for U+0027 Apostrophe in The Unicode Standard.

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.

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

Typedefs

typedef void * UMessageFormat

Functions

U_STABLE int32_t U_EXPORT2 u_formatMessage (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, UErrorCode *status,...)
U_STABLE int32_t U_EXPORT2 u_formatMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, UChar *result, int32_t resultLength, UParseError *parseError, UErrorCode *status,...)
U_STABLE void U_EXPORT2 u_parseMessage (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UErrorCode *status,...)
U_STABLE void U_EXPORT2 u_parseMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, UParseError *parseError, UErrorCode *status,...)
U_STABLE 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)
U_STABLE 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)
U_STABLE 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)
U_STABLE void U_EXPORT2 u_vparseMessageWithError (const char *locale, const UChar *pattern, int32_t patternLength, const UChar *source, int32_t sourceLength, va_list ap, UParseError *parseError, UErrorCode *status)
U_STABLE void U_EXPORT2 umsg_applyPattern (UMessageFormat *fmt, const UChar *pattern, int32_t patternLength, UParseError *parseError, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 umsg_autoQuoteApostrophe (const UChar *pattern, int32_t patternLength, UChar *dest, int32_t destCapacity, UErrorCode *ec)
U_STABLE UMessageFormat U_EXPORT2 umsg_clone (const UMessageFormat *fmt, UErrorCode *status)
U_STABLE void U_EXPORT2 umsg_close (UMessageFormat *format)
U_STABLE int32_t U_EXPORT2 umsg_format (const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status,...)
U_STABLE const char *U_EXPORT2 umsg_getLocale (const UMessageFormat *fmt)
U_STABLE UMessageFormat *U_EXPORT2 umsg_open (const UChar *pattern, int32_t patternLength, const char *locale, UParseError *parseError, UErrorCode *status)
U_STABLE void U_EXPORT2 umsg_parse (const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, UErrorCode *status,...)
U_STABLE void U_EXPORT2 umsg_setLocale (UMessageFormat *fmt, const char *locale)
U_STABLE int32_t U_EXPORT2 umsg_toPattern (const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 umsg_vformat (const UMessageFormat *fmt, UChar *result, int32_t resultLength, va_list ap, UErrorCode *status)
U_STABLE void U_EXPORT2 umsg_vparse (const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, va_list ap, UErrorCode *status)


Generated by  Doxygen 1.6.0   Back to index