icuSources/common/unicode/listformatter.h

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