util/X86MAC64/include/unicode/ulistformatter.h

   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/uformattedvalue.h"
  18
  19 #if U_SHOW_CPLUSPLUS_API
  20 #include "unicode/localpointer.h"
  21 #endif   // U_SHOW_CPLUSPLUS_API
  22
  23 /**
  24  * \file
  25  * \brief C API: Format a list in a locale-appropriate way.
  26  *
  27  * A UListFormatter is used to format a list of items in a locale-appropriate way,
  28  * using data from CLDR.
  29  * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
  30  * as "Alice, Bob, Charlie, and Delta" in English.
  31  */
  32
  33 /**
  34  * Opaque UListFormatter object for use in C
  35  * @stable ICU 55
  36  */
  37 struct UListFormatter;
  38 typedef struct UListFormatter UListFormatter;  /**< C typedef for struct UListFormatter. @stable ICU 55 */
  39
  40 struct UFormattedList;
  41 /**
  42  * Opaque struct to contain the results of a UListFormatter operation.
  43  * @stable ICU 64
  44  */
  45 typedef struct UFormattedList UFormattedList;
  46
  47 /**
  48  * FieldPosition and UFieldPosition selectors for format fields
  49  * defined by ListFormatter.
  50  * @stable ICU 63
  51  */
  52 typedef enum UListFormatterField {
  53     /**
  54      * The literal text in the result which came from the resources.
  55      * @stable ICU 63
  56      */
  57     ULISTFMT_LITERAL_FIELD,
  58     /**
  59      * The element text in the result which came from the input strings.
  60      * @stable ICU 63
  61      */
  62     ULISTFMT_ELEMENT_FIELD
  63 } UListFormatterField;
  64
  65 /**
  66  * Type of meaning expressed by the list.
  67  *
  68  * @stable ICU 67
  69  */
  70 typedef enum UListFormatterType {
  71     /**
  72      * Conjunction formatting, e.g. "Alice, Bob, Charlie, and Delta".
  73      *
  74      * @stable ICU 67
  75      */
  76     ULISTFMT_TYPE_AND,
  77
  78     /**
  79      * Disjunction (or alternative, or simply one of) formatting, e.g.
  80      * "Alice, Bob, Charlie, or Delta".
  81      *
  82      * @stable ICU 67
  83      */
  84     ULISTFMT_TYPE_OR,
  85
  86     /**
  87      * Formatting of a list of values with units, e.g. "5 pounds, 12 ounces".
  88      *
  89      * @stable ICU 67
  90      */
  91     ULISTFMT_TYPE_UNITS
  92 } UListFormatterType;
  93
  94 /**
  95  * Verbosity level of the list patterns.
  96  *
  97  * @stable ICU 67
  98  */
  99 typedef enum UListFormatterWidth {
 100     /**
 101      * Use list formatting with full words (no abbreviations) when possible.
 102      *
 103      * @stable ICU 67
 104      */
 105     ULISTFMT_WIDTH_WIDE,
 106
 107     /**
 108      * Use list formatting of typical length.
 109      * @stable ICU 67
 110      */
 111     ULISTFMT_WIDTH_SHORT,
 112
 113     /**
 114      * Use list formatting of the shortest possible length.
 115      * @stable ICU 67
 116      */
 117     ULISTFMT_WIDTH_NARROW,
 118 } UListFormatterWidth;
 119
 120 /**
 121  * Open a new UListFormatter object using the rules for a given locale.
 122  * The object will be initialized with AND type and WIDE width.
 123  *
 124  * @param locale
 125  *            The locale whose rules should be used; may be NULL for
 126  *            default locale.
 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  *            A pointer to a UListFormatter object for the specified locale,
 135  *            or NULL if an error occurred.
 136  * @stable ICU 55
 137  */
 138 U_CAPI UListFormatter* U_EXPORT2
 139 ulistfmt_open(const char*  locale,
 140               UErrorCode*  status);
 141
 142 /**
 143  * Open a new UListFormatter object appropriate for the given locale, list type,
 144  * and style.
 145  *
 146  * @param locale
 147  *            The locale whose rules should be used; may be NULL for
 148  *            default locale.
 149  * @param type
 150  *            The type of list formatting to use.
 151  * @param width
 152  *            The width of formatting to use.
 153  * @param status
 154  *            A pointer to a standard ICU UErrorCode (input/output parameter).
 155  *            Its input value must pass the U_SUCCESS() test, or else the
 156  *            function returns immediately. The caller should check its output
 157  *            value with U_FAILURE(), or use with function chaining (see User
 158  *            Guide for details).
 159  * @return
 160  *            A pointer to a UListFormatter object for the specified locale,
 161  *            or NULL if an error occurred.
 162  * @stable ICU 67
 163  */
 164 U_CAPI UListFormatter* U_EXPORT2
 165 ulistfmt_openForType(const char*  locale, UListFormatterType type,
 166                      UListFormatterWidth width, UErrorCode*  status);
 167
 168 /**
 169  * Close a UListFormatter object. Once closed it may no longer be used.
 170  * @param listfmt
 171  *            The UListFormatter object to close.
 172  * @stable ICU 55
 173  */
 174 U_CAPI void U_EXPORT2
 175 ulistfmt_close(UListFormatter *listfmt);
 176
 177 /**
 178  * Creates an object to hold the result of a UListFormatter
 179  * operation. The object can be used repeatedly; it is cleared whenever
 180  * passed to a format function.
 181  *
 182  * @param ec Set if an error occurs.
 183  * @return A pointer needing ownership.
 184  * @stable ICU 64
 185  */
 186 U_CAPI UFormattedList* U_EXPORT2
 187 ulistfmt_openResult(UErrorCode* ec);
 188
 189 /**
 190  * Returns a representation of a UFormattedList as a UFormattedValue,
 191  * which can be subsequently passed to any API requiring that type.
 192  *
 193  * The returned object is owned by the UFormattedList and is valid
 194  * only as long as the UFormattedList is present and unchanged in memory.
 195  *
 196  * You can think of this method as a cast between types.
 197  *
 198  * When calling ufmtval_nextPosition():
 199  * The fields are returned from start to end. The special field category
 200  * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument
 201  * was inserted at the given position. The span category will
 202  * always occur before the corresponding instance of UFIELD_CATEGORY_LIST
 203  * in the ufmtval_nextPosition() iterator.
 204  *
 205  * @param uresult The object containing the formatted string.
 206  * @param ec Set if an error occurs.
 207  * @return A UFormattedValue owned by the input object.
 208  * @stable ICU 64
 209  */
 210 U_CAPI const UFormattedValue* U_EXPORT2
 211 ulistfmt_resultAsValue(const UFormattedList* uresult, UErrorCode* ec);
 212
 213 /**
 214  * Releases the UFormattedList created by ulistfmt_openResult().
 215  *
 216  * @param uresult The object to release.
 217  * @stable ICU 64
 218  */
 219 U_CAPI void U_EXPORT2
 220 ulistfmt_closeResult(UFormattedList* uresult);
 221
 222
 223 #if U_SHOW_CPLUSPLUS_API
 224
 225 U_NAMESPACE_BEGIN
 226
 227 /**
 228  * \class LocalUListFormatterPointer
 229  * "Smart pointer" class, closes a UListFormatter via ulistfmt_close().
 230  * For most methods see the LocalPointerBase base class.
 231  *
 232  * @see LocalPointerBase
 233  * @see LocalPointer
 234  * @stable ICU 55
 235  */
 236 U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close);
 237
 238 /**
 239  * \class LocalUFormattedListPointer
 240  * "Smart pointer" class, closes a UFormattedList via ulistfmt_closeResult().
 241  * For most methods see the LocalPointerBase base class.
 242  *
 243  * @see LocalPointerBase
 244  * @see LocalPointer
 245  * @stable ICU 64
 246  */
 247 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult);
 248
 249 U_NAMESPACE_END
 250
 251 #endif
 252
 253 /**
 254  * Formats a list of strings using the conventions established for the
 255  * UListFormatter object.
 256  * @param listfmt
 257  *            The UListFormatter object specifying the list conventions.
 258  * @param strings
 259  *            An array of pointers to UChar strings; the array length is
 260  *            specified by stringCount. Must be non-NULL if stringCount > 0.
 261  * @param stringLengths
 262  *            An array of string lengths corresponding to the strings[]
 263  *            parameter; any individual length value may be negative to indicate
 264  *            that the corresponding strings[] entry is 0-terminated, or
 265  *            stringLengths itself may be NULL if all of the strings are
 266  *            0-terminated. If non-NULL, the stringLengths array must have
 267  *            stringCount entries.
 268  * @param stringCount
 269  *            the number of entries in strings[], and the number of entries
 270  *            in the stringLengths array if it is not NULL. Must be >= 0.
 271  * @param result
 272  *            A pointer to a buffer to receive the formatted list.
 273  * @param resultCapacity
 274  *            The maximum size of result.
 275  * @param status
 276  *            A pointer to a standard ICU UErrorCode (input/output parameter).
 277  *            Its input value must pass the U_SUCCESS() test, or else the
 278  *            function returns immediately. The caller should check its output
 279  *            value with U_FAILURE(), or use with function chaining (see User
 280  *            Guide for details).
 281  * @return
 282  *            The total buffer size needed; if greater than resultLength, the
 283  *            output was truncated. May be <=0 if unable to determine the
 284  *            total buffer size needed (e.g. for illegal arguments).
 285  * @stable ICU 55
 286  */
 287 U_CAPI int32_t U_EXPORT2
 288 ulistfmt_format(const UListFormatter* listfmt,
 289                 const UChar* const strings[],
 290                 const int32_t *    stringLengths,
 291                 int32_t            stringCount,
 292                 UChar*             result,
 293                 int32_t            resultCapacity,
 294                 UErrorCode*        status);
 295
 296 /**
 297  * Formats a list of strings to a UFormattedList, which exposes more
 298  * information than the string exported by ulistfmt_format().
 299  *
 300  * @param listfmt
 301  *            The UListFormatter object specifying the list conventions.
 302  * @param strings
 303  *            An array of pointers to UChar strings; the array length is
 304  *            specified by stringCount. Must be non-NULL if stringCount > 0.
 305  * @param stringLengths
 306  *            An array of string lengths corresponding to the strings[]
 307  *            parameter; any individual length value may be negative to indicate
 308  *            that the corresponding strings[] entry is 0-terminated, or
 309  *            stringLengths itself may be NULL if all of the strings are
 310  *            0-terminated. If non-NULL, the stringLengths array must have
 311  *            stringCount entries.
 312  * @param stringCount
 313  *            the number of entries in strings[], and the number of entries
 314  *            in the stringLengths array if it is not NULL. Must be >= 0.
 315  * @param uresult
 316  *            The object in which to store the result of the list formatting
 317  *            operation. See ulistfmt_openResult().
 318  * @param status
 319  *            Error code set if an error occurred during formatting.
 320  * @stable ICU 64
 321  */
 322 U_CAPI void U_EXPORT2
 323 ulistfmt_formatStringsToResult(
 324                 const UListFormatter* listfmt,
 325                 const UChar* const strings[],
 326                 const int32_t *    stringLengths,
 327                 int32_t            stringCount,
 328                 UFormattedList*    uresult,
 329                 UErrorCode*        status);
 330
 331 #endif /* #if !UCONFIG_NO_FORMATTING */
 332
 333 #endif