icuSources/common/unicode/listformatter.h

   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