1 // Copyright (C) 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 /** 37 * Open a new UListFormatter object using the rules for a given locale. 38 * @param locale 39 * The locale whose rules should be used; may be NULL for 40 * default locale. 41 * @param status 42 * A pointer to a standard ICU UErrorCode (input/output parameter). 43 * Its input value must pass the U_SUCCESS() test, or else the 44 * function returns immediately. The caller should check its output 45 * value with U_FAILURE(), or use with function chaining (see User 46 * Guide for details). 47 * @return 48 * A pointer to a UListFormatter object for the specified locale, 49 * or NULL if an error occurred. 50 * @stable ICU 55 51 */ 52 U_STABLE UListFormatter* U_EXPORT2 53 ulistfmt_open(const char* locale, 54 UErrorCode* status); 55 56 /** 57 * Close a UListFormatter object. Once closed it may no longer be used. 58 * @param listfmt 59 * The UListFormatter object to close. 60 * @stable ICU 55 61 */ 62 U_STABLE void U_EXPORT2 63 ulistfmt_close(UListFormatter *listfmt); 64 65 66 #if U_SHOW_CPLUSPLUS_API 67 68 U_NAMESPACE_BEGIN 69 70 /** 71 * \class LocalUListFormatterPointer 72 * "Smart pointer" class, closes a UListFormatter via ulistfmt_close(). 73 * For most methods see the LocalPointerBase base class. 74 * 75 * @see LocalPointerBase 76 * @see LocalPointer 77 * @stable ICU 55 78 */ 79 U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close); 80 81 U_NAMESPACE_END 82 83 #endif 84 85 /** 86 * Formats a list of strings using the conventions established for the 87 * UListFormatter object. 88 * @param listfmt 89 * The UListFormatter object specifying the list conventions. 90 * @param strings 91 * An array of pointers to UChar strings; the array length is 92 * specified by stringCount. Must be non-NULL if stringCount > 0. 93 * @param stringLengths 94 * An array of string lengths corresponding to the strings[] 95 * parameter; any individual length value may be negative to indicate 96 * that the corresponding strings[] entry is 0-terminated, or 97 * stringLengths itself may be NULL if all of the strings are 98 * 0-terminated. If non-NULL, the stringLengths array must have 99 * stringCount entries. 100 * @param stringCount 101 * the number of entries in strings[], and the number of entries 102 * in the stringLengths array if it is not NULL. Must be >= 0. 103 * @param result 104 * A pointer to a buffer to receive the formatted list. 105 * @param resultCapacity 106 * The maximum size of result. 107 * @param status 108 * A pointer to a standard ICU UErrorCode (input/output parameter). 109 * Its input value must pass the U_SUCCESS() test, or else the 110 * function returns immediately. The caller should check its output 111 * value with U_FAILURE(), or use with function chaining (see User 112 * Guide for details). 113 * @return 114 * The total buffer size needed; if greater than resultLength, the 115 * output was truncated. May be <=0 if unable to determine the 116 * total buffer size needed (e.g. for illegal arguments). 117 * @stable ICU 55 118 */ 119 U_DRAFT int32_t U_EXPORT2 120 ulistfmt_format(const UListFormatter* listfmt, 121 const UChar* const strings[], 122 const int32_t * stringLengths, 123 int32_t stringCount, 124 UChar* result, 125 int32_t resultCapacity, 126 UErrorCode* status); 127 128 #endif /* #if !UCONFIG_NO_FORMATTING */ 129 130 #endif 131