icuSources/common/unicode/ulistformatter.h

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