source/common/unicode/listformatter.h

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