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