OLD | NEW |
(Empty) | |
| 1 /* |
| 2 ********************************************************************************
********* |
| 3 * Copyright (C) 2015, International Business Machines |
| 4 * Corporation and others. All Rights Reserved. |
| 5 ********************************************************************************
********* |
| 6 */ |
| 7 |
| 8 #ifndef ULISTFORMATTER_H |
| 9 #define ULISTFORMATTER_H |
| 10 |
| 11 #include "unicode/utypes.h" |
| 12 |
| 13 #if !UCONFIG_NO_FORMATTING |
| 14 #ifndef U_HIDE_DRAFT_API |
| 15 |
| 16 #include "unicode/localpointer.h" |
| 17 |
| 18 /** |
| 19 * \file |
| 20 * \brief C API: Format a list in a locale-appropriate way. |
| 21 * |
| 22 * A UListFormatter is used to format a list of items in a locale-appropriate wa
y, |
| 23 * using data from CLDR. |
| 24 * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted |
| 25 * as "Alice, Bob, Charlie, and Delta" in English. |
| 26 */ |
| 27 |
| 28 /** |
| 29 * Opaque UListFormatter object for use in C |
| 30 * @draft ICU 55 |
| 31 */ |
| 32 struct UListFormatter; |
| 33 typedef struct UListFormatter UListFormatter; /**< C typedef for struct UListFo
rmatter. @draft ICU 55 */ |
| 34 |
| 35 /** |
| 36 * Open a new UListFormatter object using the rules for a given locale. |
| 37 * @param locale |
| 38 * The locale whose rules should be used; may be NULL for |
| 39 * default locale. |
| 40 * @param status |
| 41 * A pointer to a standard ICU UErrorCode (input/output parameter). |
| 42 * Its input value must pass the U_SUCCESS() test, or else the |
| 43 * function returns immediately. The caller should check its output |
| 44 * value with U_FAILURE(), or use with function chaining (see User |
| 45 * Guide for details). |
| 46 * @return |
| 47 * A pointer to a UListFormatter object for the specified locale, |
| 48 * or NULL if an error occurred. |
| 49 * @draft ICU 55 |
| 50 */ |
| 51 U_DRAFT UListFormatter* U_EXPORT2 |
| 52 ulistfmt_open(const char* locale, |
| 53 UErrorCode* status); |
| 54 |
| 55 /** |
| 56 * Close a UListFormatter object. Once closed it may no longer be used. |
| 57 * @param listfmt |
| 58 * The UListFormatter object to close. |
| 59 * @draft ICU 55 |
| 60 */ |
| 61 U_DRAFT void U_EXPORT2 |
| 62 ulistfmt_close(UListFormatter *listfmt); |
| 63 |
| 64 |
| 65 #if U_SHOW_CPLUSPLUS_API |
| 66 |
| 67 U_NAMESPACE_BEGIN |
| 68 |
| 69 /** |
| 70 * \class LocalUListFormatterPointer |
| 71 * "Smart pointer" class, closes a UListFormatter via ulistfmt_close(). |
| 72 * For most methods see the LocalPointerBase base class. |
| 73 * |
| 74 * @see LocalPointerBase |
| 75 * @see LocalPointer |
| 76 * @draft ICU 55 |
| 77 */ |
| 78 U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt
_close); |
| 79 |
| 80 U_NAMESPACE_END |
| 81 |
| 82 #endif |
| 83 |
| 84 /** |
| 85 * Formats a list of strings using the conventions established for the |
| 86 * UListFormatter object. |
| 87 * @param listfmt |
| 88 * The UListFormatter object specifying the list conventions. |
| 89 * @param strings |
| 90 * An array of pointers to UChar strings; the array length is |
| 91 * specified by stringCount. Must be non-NULL if stringCount > 0. |
| 92 * @param stringLengths |
| 93 * An array of string lengths corresponding to the strings[] |
| 94 * parameter; any individual length value may be negative to indicate |
| 95 * that the corresponding strings[] entry is 0-terminated, or |
| 96 * stringLengths itself may be NULL if all of the strings are |
| 97 * 0-terminated. If non-NULL, the stringLengths array must have |
| 98 * stringCount entries. |
| 99 * @param stringCount |
| 100 * the number of entries in strings[], and the number of entries |
| 101 * in the stringLengths array if it is not NULL. Must be >= 0. |
| 102 * @param result |
| 103 * A pointer to a buffer to receive the formatted list. |
| 104 * @param resultCapacity |
| 105 * The maximum size of result. |
| 106 * @param status |
| 107 * A pointer to a standard ICU UErrorCode (input/output parameter). |
| 108 * Its input value must pass the U_SUCCESS() test, or else the |
| 109 * function returns immediately. The caller should check its output |
| 110 * value with U_FAILURE(), or use with function chaining (see User |
| 111 * Guide for details). |
| 112 * @return |
| 113 * The total buffer size needed; if greater than resultLength, the |
| 114 * output was truncated. May be <=0 if unable to determine the |
| 115 * total buffer size needed (e.g. for illegal arguments). |
| 116 * @draft ICU 55 |
| 117 */ |
| 118 U_DRAFT int32_t U_EXPORT2 |
| 119 ulistfmt_format(const UListFormatter* listfmt, |
| 120 const UChar* const strings[], |
| 121 const int32_t * stringLengths, |
| 122 int32_t stringCount, |
| 123 UChar* result, |
| 124 int32_t resultCapacity, |
| 125 UErrorCode* status); |
| 126 |
| 127 #endif /* U_HIDE_DRAFT_API */ |
| 128 #endif /* #if !UCONFIG_NO_FORMATTING */ |
| 129 |
| 130 #endif |
OLD | NEW |