-/*
-*******************************************************************************
-* Copyright (C) 1996-2003, International Business Machines Corporation and others. All Rights Reserved.
-*******************************************************************************
-*
-* file name: umsg.h
-* encoding: US-ASCII
-* tab size: 8 (not used)
-* indentation:4
-*
-* Change history:
-*
-* 08/5/2001 Ram Added C wrappers for C++ API.
-*
-*
-*/
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+/********************************************************************
+ * COPYRIGHT:
+ * Copyright (c) 1997-2011, International Business Machines Corporation and
+ * others. All Rights Reserved.
+ * Copyright (C) 2010 , Yahoo! Inc.
+ ********************************************************************
+ *
+ * file name: umsg.h
+ * encoding: UTF-8
+ * tab size: 8 (not used)
+ * indentation:4
+ *
+ * Change history:
+ *
+ * 08/5/2001 Ram Added C wrappers for C++ API.
+ ********************************************************************/
#ifndef UMSG_H
#define UMSG_H
#if !UCONFIG_NO_FORMATTING
+#include "unicode/localpointer.h"
+#include "unicode/uloc.h"
#include "unicode/parseerr.h"
#include <stdarg.h>
+
/**
* \file
* \brief C API: MessageFormat
*
- * <h2>Message Format C API </h2>
+ * <h2>MessageFormat C API </h2>
*
- * Provides means to produce concatenated messages in language-neutral way.
- * Use this for all concatenations that show up to end users.
- * <P>
- * Takes a set of objects, formats them, then inserts the formatted
- * strings into the pattern at the appropriate places.
- * <P>
- * Here are some examples of usage:
+ * <p>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.
+ *
+ * <p>The opaque UMessageFormat type is a thin C wrapper around
+ * a C++ MessageFormat. It is constructed from a <em>pattern</em> string
+ * with arguments in {curly braces} which will be replaced by formatted values.
+ *
+ * <p>Currently, the C API supports only numbered arguments.
+ *
+ * <p>For details about the pattern syntax and behavior,
+ * especially about the ASCII apostrophe vs. the
+ * real apostrophe (single quote) character \htmlonly’\endhtmlonly (U+2019),
+ * see the C++ MessageFormat class documentation.
+ *
+ * <p>Here are some examples of C API usage:
* Example 1:
* <pre>
* \code
* 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);
+ * 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;
* \endcode
* </pre>
*
- * The pattern is of the following form. Legend:
- * <pre>
- * \code
- * {optional item}
- * (group that may be repeated)*
- * \endcode
- * </pre>
- * Do not confuse optional items with items inside quotes braces, such
- * as this: "{". Quoted braces are literals.
- * <pre>
- * \code
- * 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
- * \endcode
- * </pre>
- * 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.
- * <P>
- * 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".
- * <P>
- * 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.
- * <P>
- * The argument is a number from 0 to 9, which corresponds to the
- * arguments presented in an array to be formatted.
- * <P>
- * 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.
- * <P>
-
- * <P>
- * [Note:] As we see above, the string produced by a choice Format in
- * MessageFormat is treated specially; occurances of '{' are used to
- * indicated subformats.
- * <P>
- * [Note:] Formats are numbered by order of variable in the string.
- * This is [not] the same as the argument numbering!
+ * Example 3:
* <pre>
* \code
- * 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}
+ * 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);
+ * }
* \endcode
- * </pre>
- * and so on.
+ * </pre>
*/
/**
* @see u_parseMessage
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
u_formatMessage(const char *locale,
const UChar *pattern,
int32_t patternLength,
* @see u_parseMessage
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
u_vformatMessage( const char *locale,
const UChar *pattern,
int32_t patternLength,
* 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}.
+ * This function is not able to parse all output from {@link #u_formatMessage }.
* @param locale The locale for which the message is formatted
* @param pattern The pattern specifying the message's format
* @param patternLength The length of pattern
* @see u_formatMessage
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
u_parseMessage( const char *locale,
const UChar *pattern,
int32_t patternLength,
* 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}.
+ * This function is not able to parse all output from {@link #u_formatMessage }.
* @param locale The locale for which the message is formatted
* @param pattern The pattern specifying the message's format
* @param patternLength The length of pattern
* @see u_formatMessage
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
u_vparseMessage(const char *locale,
const UChar *pattern,
int32_t patternLength,
* @see u_parseMessage
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
u_formatMessageWithError( const char *locale,
const UChar *pattern,
int32_t patternLength,
* output was truncated.
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
u_vformatMessageWithError( const char *locale,
const UChar *pattern,
int32_t patternLength,
* 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}.
+ * This function is not able to parse all output from {@link #u_formatMessage }.
* @param locale The locale for which the message is formatted
* @param pattern The pattern specifying the message's format
* @param patternLength The length of pattern
* @see u_formatMessage
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
u_parseMessageWithError(const char *locale,
const UChar *pattern,
int32_t patternLength,
* 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}.
+ * This function is not able to parse all output from {@link #u_formatMessage }.
* @param locale The locale for which the message is formatted
* @param pattern The pattern specifying the message's format
* @param patternLength The length of pattern
* @see u_formatMessage
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
u_vparseMessageWithError(const char *locale,
const UChar *pattern,
int32_t patternLength,
* messages, or 0 if an error occurred.
* @stable ICU 2.0
*/
-U_CAPI UMessageFormat* U_EXPORT2
+U_STABLE UMessageFormat* U_EXPORT2
umsg_open( const UChar *pattern,
int32_t patternLength,
const char *locale,
* @param format The formatter to close.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
umsg_close(UMessageFormat* format);
+#if U_SHOW_CPLUSPLUS_API
+
+U_NAMESPACE_BEGIN
+
+/**
+ * \class LocalUMessageFormatPointer
+ * "Smart pointer" class, closes a UMessageFormat via umsg_close().
+ * For most methods see the LocalPointerBase base class.
+ *
+ * @see LocalPointerBase
+ * @see LocalPointer
+ * @stable ICU 4.4
+ */
+U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close);
+
+U_NAMESPACE_END
+
+#endif
+
/**
* Open a copy of a UMessageFormat.
* This function performs a deep copy.
* @return A pointer to a UDateFormat identical to fmt.
* @stable ICU 2.0
*/
-U_CAPI UMessageFormat U_EXPORT2
+U_STABLE UMessageFormat U_EXPORT2
umsg_clone(const UMessageFormat *fmt,
UErrorCode *status);
* @param locale The locale the formatter should use.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
umsg_setLocale(UMessageFormat *fmt,
const char* locale);
* @return the locale.
* @stable ICU 2.0
*/
-U_CAPI const char* U_EXPORT2
-umsg_getLocale(UMessageFormat *fmt);
+U_STABLE const char* U_EXPORT2
+umsg_getLocale(const UMessageFormat *fmt);
/**
* Sets the pattern.
* set to a failure result.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
umsg_applyPattern( UMessageFormat *fmt,
const UChar* pattern,
int32_t patternLength,
* @return the pattern of the format
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
-umsg_toPattern(UMessageFormat *fmt,
+U_STABLE int32_t U_EXPORT2
+umsg_toPattern(const UMessageFormat *fmt,
UChar* result,
int32_t resultLength,
UErrorCode* status);
* the output was truncated.
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
-umsg_format( UMessageFormat *fmt,
+U_STABLE int32_t U_EXPORT2
+umsg_format( const UMessageFormat *fmt,
UChar *result,
int32_t resultLength,
UErrorCode *status,
* the output was truncated.
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
-umsg_vformat( UMessageFormat *fmt,
+U_STABLE int32_t U_EXPORT2
+umsg_vformat( const UMessageFormat *fmt,
UChar *result,
int32_t resultLength,
va_list ap,
* 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{umsg_format}.
+ * This function is not able to parse all output from {@link #umsg_format }.
* @param fmt The formatter to use
* @param source The text to parse.
* @param sourceLength The length of source, or -1 if null-terminated.
* specified in pattern.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
-umsg_parse( UMessageFormat *fmt,
+U_STABLE void U_EXPORT2
+umsg_parse( const UMessageFormat *fmt,
const UChar *source,
int32_t sourceLength,
int32_t *count,
* 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{umsg_format}.
+ * This function is not able to parse all output from {@link #umsg_format }.
* @param fmt The formatter to use
* @param source The text to parse.
* @param sourceLength The length of source, or -1 if null-terminated.
* @see u_formatMessage
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
-umsg_vparse(UMessageFormat *fmt,
+U_STABLE void U_EXPORT2
+umsg_vparse(const UMessageFormat *fmt,
const UChar *source,
int32_t sourceLength,
int32_t *count,
va_list ap,
UErrorCode *status);
+
+/**
+ * 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.
+ *
+ * <p><b>Note</b> 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.
+ *
+ * @param pattern the 'apostrophe-friendly' patttern to convert
+ * @param patternLength the length of pattern, or -1 if unknown and pattern is null-terminated
+ * @param dest the buffer for the result, or NULL if preflight only
+ * @param destCapacity the length of the buffer, or 0 if preflighting
+ * @param ec the error code
+ * @return 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
+ */
+U_STABLE int32_t U_EXPORT2
+umsg_autoQuoteApostrophe(const UChar* pattern,
+ int32_t patternLength,
+ UChar* dest,
+ int32_t destCapacity,
+ UErrorCode* ec);
+
#endif /* #if !UCONFIG_NO_FORMATTING */
#endif
projects / apple / icu.git / blobdiff