Home | History | Annotate | Download | only in unicode 
      1 /*
      2 *******************************************************************************
      3 *
      4 *   Copyright (C) 2012-2014, International Business Machines
      5 *   Corporation and others.  All Rights Reserved.
      6 *
      7 *******************************************************************************
      8 *   file name:  listformatter.h
      9 *   encoding:   US-ASCII
     10 *   tab size:   8 (not used)
     11 *   indentation:4
     12 *
     13 *   created on: 20120426
     14 *   created by: Umesh P. Nair
     15 */
     16 
     17 #ifndef __LISTFORMATTER_H__
     18 #define __LISTFORMATTER_H__
     19 
     20 #include "unicode/utypes.h"
     21 
     22 #include "unicode/unistr.h"
     23 #include "unicode/locid.h"
     24 
     25 U_NAMESPACE_BEGIN
     26 
     27 /** @internal */
     28 class Hashtable;
     29 
     30 /** @internal */
     31 struct ListFormatInternal;
     32 
     33 /* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
     34 /** @internal */
     35 struct ListFormatData : public UMemory {
     36     UnicodeString twoPattern;
     37     UnicodeString startPattern;
     38     UnicodeString middlePattern;
     39     UnicodeString endPattern;
     40 
     41   ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
     42       twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
     43 };
     44 
     45 
     46 /**
     47  * \file
     48  * \brief C++ API: API for formatting a list.
     49  */
     50 
     51 
     52 /**
     53  * An immutable class for formatting a list, using data from CLDR (or supplied
     54  * separately).
     55  *
     56  * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
     57  * as "Alice, Bob, Charlie and Delta" in English.
     58  *
     59  * The ListFormatter class is not intended for public subclassing.
     60  * @stable ICU 50
     61  */
     62 class U_COMMON_API ListFormatter : public UObject{
     63 
     64   public:
     65 
     66     /**
     67      * Copy constructor.
     68      * @draft ICU 52
     69      */
     70     ListFormatter(const ListFormatter&);
     71 
     72     /**
     73      * Assignment operator.
     74      * @draft ICU 52
     75      */
     76     ListFormatter& operator=(const ListFormatter& other);
     77 
     78     /**
     79      * Creates a ListFormatter appropriate for the default locale.
     80      *
     81      * @param errorCode ICU error code, set if no data available for default locale.
     82      * @return Pointer to a ListFormatter object for the default locale,
     83      *     created from internal data derived from CLDR data.
     84      * @stable ICU 50
     85      */
     86     static ListFormatter* createInstance(UErrorCode& errorCode);
     87 
     88     /**
     89      * Creates a ListFormatter appropriate for a locale.
     90      *
     91      * @param locale The locale.
     92      * @param errorCode ICU error code, set if no data available for the given locale.
     93      * @return A ListFormatter object created from internal data derived from
     94      *     CLDR data.
     95      * @stable ICU 50
     96      */
     97     static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode);
     98 
     99 #ifndef U_HIDE_INTERNAL_API
    100     /**
    101      * Creates a ListFormatter appropriate for a locale and style.
    102      *
    103      * @param locale The locale.
    104      * @param style the style, either "standard", "duration", or "duration-short"
    105      * @param errorCode ICU error code, set if no data available for the given locale.
    106      * @return A ListFormatter object created from internal data derived from
    107      *     CLDR data.
    108      * @internal
    109      */
    110     static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode);
    111 #endif  /* U_HIDE_INTERNAL_API */
    112 
    113     /**
    114      * Destructor.
    115      *
    116      * @stable ICU 50
    117      */
    118     virtual ~ListFormatter();
    119 
    120 
    121     /**
    122      * Formats a list of strings.
    123      *
    124      * @param items An array of strings to be combined and formatted.
    125      * @param n_items Length of the array items.
    126      * @param appendTo The string to which the result should be appended to.
    127      * @param errorCode ICU error code, set if there is an error.
    128      * @return Formatted string combining the elements of items, appended to appendTo.
    129      * @stable ICU 50
    130      */
    131     UnicodeString& format(const UnicodeString items[], int32_t n_items,
    132         UnicodeString& appendTo, UErrorCode& errorCode) const;
    133 
    134 #ifndef U_HIDE_INTERNAL_API
    135     /**
    136       @internal for MeasureFormat
    137     */
    138     UnicodeString& format(
    139             const UnicodeString items[],
    140             int32_t n_items,
    141             UnicodeString& appendTo,
    142             int32_t index,
    143             int32_t &offset,
    144             UErrorCode& errorCode) const;
    145     /**
    146      * @internal constructor made public for testing.
    147      */
    148     ListFormatter(const ListFormatData &data);
    149     /**
    150      * @internal constructor made public for testing.
    151      */
    152     ListFormatter(const ListFormatInternal* listFormatterInternal);
    153 #endif  /* U_HIDE_INTERNAL_API */
    154 
    155   private:
    156     static void initializeHash(UErrorCode& errorCode);
    157     static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode);
    158 
    159     ListFormatter();
    160 
    161     ListFormatInternal* owned;
    162     const ListFormatInternal* data;
    163 };
    164 
    165 U_NAMESPACE_END
    166 
    167 #endif
    168