Home | History | Annotate | Download | only in unicode 
      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
    131