icuSources/common/unicode/ulistformatter.h

   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 way,
  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 UListFormatter. @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