icuSources/common/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/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_CAPI 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_CAPI 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 // U_SHOW_CPLUSPLUS_API
  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_CAPI 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