icuSources/i18n/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 #include "unicode/formattedvalue.h"
  27
  28 #if U_SHOW_CPLUSPLUS_API
  29 U_NAMESPACE_BEGIN
  30
  31 class FieldPositionIterator;
  32 class FieldPositionHandler;
  33 class FormattedListData;
  34 class ListFormatter;
  35
  36 /** @internal */
  37 class Hashtable;
  38
  39 /** @internal */
  40 struct ListFormatInternal;
  41
  42 /* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
  43 /**
  44  * @internal
  45  * \cond
  46  */
  47 struct ListFormatData : public UMemory {
  48     UnicodeString twoPattern;
  49     UnicodeString startPattern;
  50     UnicodeString middlePattern;
  51     UnicodeString endPattern;
  52
  53   ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
  54       twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
  55 };
  56 /** \endcond */
  57
  58
  59 /**
  60  * \file
  61  * \brief C++ API: API for formatting a list.
  62  */
  63
  64
  65 #if !UCONFIG_NO_FORMATTING
  66 #ifndef U_HIDE_DRAFT_API
  67 /**
  68  * An immutable class containing the result of a list formatting operation.
  69  *
  70  * Instances of this class are immutable and thread-safe.
  71  *
  72  * When calling nextPosition():
  73  * The fields are returned from start to end. The special field category
  74  * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument
  75  * was inserted at the given position. The span category will
  76  * always occur before the corresponding instance of UFIELD_CATEGORY_LIST
  77  * in the nextPosition() iterator.
  78  *
  79  * Not intended for public subclassing.
  80  *
  81  * @draft ICU 64
  82  */
  83 class U_I18N_API FormattedList : public UMemory, public FormattedValue {
  84   public:
  85     /**
  86      * Default constructor; makes an empty FormattedList.
  87      * @draft ICU 64
  88      */
  89     FormattedList() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
  90
  91     /**
  92      * Move constructor: Leaves the source FormattedList in an undefined state.
  93      * @draft ICU 64
  94      */
  95     FormattedList(FormattedList&& src) U_NOEXCEPT;
  96
  97     /**
  98      * Destruct an instance of FormattedList.
  99      * @draft ICU 64
 100      */
 101     virtual ~FormattedList() U_OVERRIDE;
 102
 103     /** Copying not supported; use move constructor instead. */
 104     FormattedList(const FormattedList&) = delete;
 105
 106     /** Copying not supported; use move assignment instead. */
 107     FormattedList& operator=(const FormattedList&) = delete;
 108
 109     /**
 110      * Move assignment: Leaves the source FormattedList in an undefined state.
 111      * @draft ICU 64
 112      */
 113     FormattedList& operator=(FormattedList&& src) U_NOEXCEPT;
 114
 115     /** @copydoc FormattedValue::toString() */
 116     UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
 117
 118     /** @copydoc FormattedValue::toTempString() */
 119     UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
 120
 121     /** @copydoc FormattedValue::appendTo() */
 122     Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE;
 123
 124     /** @copydoc FormattedValue::nextPosition() */
 125     UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
 126
 127   private:
 128     FormattedListData *fData;
 129     UErrorCode fErrorCode;
 130     explicit FormattedList(FormattedListData *results)
 131         : fData(results), fErrorCode(U_ZERO_ERROR) {}
 132     explicit FormattedList(UErrorCode errorCode)
 133         : fData(nullptr), fErrorCode(errorCode) {}
 134     friend class ListFormatter;
 135 };
 136 #endif /* U_HIDE_DRAFT_API */
 137 #endif // !UCONFIG_NO_FORMATTING
 138
 139
 140 /**
 141  * An immutable class for formatting a list, using data from CLDR (or supplied
 142  * separately).
 143  *
 144  * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
 145  * as "Alice, Bob, Charlie and Delta" in English.
 146  *
 147  * The ListFormatter class is not intended for public subclassing.
 148  * @stable ICU 50
 149  */
 150 class U_I18N_API ListFormatter : public UObject{
 151
 152   public:
 153
 154     /**
 155      * Copy constructor.
 156      * @stable ICU 52
 157      */
 158     ListFormatter(const ListFormatter&);
 159
 160     /**
 161      * Assignment operator.
 162      * @stable ICU 52
 163      */
 164     ListFormatter& operator=(const ListFormatter& other);
 165
 166     /**
 167      * Creates a ListFormatter appropriate for the default locale.
 168      *
 169      * @param errorCode ICU error code, set if no data available for default locale.
 170      * @return Pointer to a ListFormatter object for the default locale,
 171      *     created from internal data derived from CLDR data.
 172      * @stable ICU 50
 173      */
 174     static ListFormatter* createInstance(UErrorCode& errorCode);
 175
 176     /**
 177      * Creates a ListFormatter appropriate for a locale.
 178      *
 179      * @param locale The locale.
 180      * @param errorCode ICU error code, set if no data available for the given locale.
 181      * @return A ListFormatter object created from internal data derived from
 182      *     CLDR data.
 183      * @stable ICU 50
 184      */
 185     static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode);
 186
 187 #ifndef U_HIDE_INTERNAL_API
 188     /**
 189      * Creates a ListFormatter appropriate for a locale and style.
 190      *
 191      * @param locale The locale.
 192      * @param style the style, either "standard", "or", "unit", "unit-narrow", or "unit-short"
 193      * @param errorCode ICU error code, set if no data available for the given locale.
 194      * @return A ListFormatter object created from internal data derived from
 195      *     CLDR data.
 196      * @internal
 197      */
 198     static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode);
 199 #endif  /* U_HIDE_INTERNAL_API */
 200
 201     /**
 202      * Destructor.
 203      *
 204      * @stable ICU 50
 205      */
 206     virtual ~ListFormatter();
 207
 208
 209     /**
 210      * Formats a list of strings.
 211      *
 212      * @param items An array of strings to be combined and formatted.
 213      * @param n_items Length of the array items.
 214      * @param appendTo The string to which the result should be appended to.
 215      * @param errorCode ICU error code, set if there is an error.
 216      * @return Formatted string combining the elements of items, appended to appendTo.
 217      * @stable ICU 50
 218      */
 219     UnicodeString& format(const UnicodeString items[], int32_t n_items,
 220         UnicodeString& appendTo, UErrorCode& errorCode) const;
 221
 222 #ifndef U_HIDE_DRAFT_API
 223     /**
 224      * Format a list of strings.
 225      *
 226      * @param items     An array of strings to be combined and formatted.
 227      * @param n_items   Length of the array items.
 228      * @param appendTo  The string to which the formatted result will be
 229      *                  appended.
 230      * @param posIter   On return, can be used to iterate over positions of
 231      *                  fields generated by this format call. Field values are
 232      *                  defined in UListFormatterField. Can be NULL.
 233      * @param errorCode ICU error code returned here.
 234      * @return          Formatted string combining the elements of items,
 235      *                  appended to appendTo.
 236      * @draft ICU 63
 237      */
 238     UnicodeString& format(const UnicodeString items[], int32_t n_items,
 239         UnicodeString & appendTo, FieldPositionIterator* posIter,
 240         UErrorCode& errorCode) const;
 241 #endif  /* U_HIDE_DRAFT_API */
 242
 243 #if !UCONFIG_NO_FORMATTING
 244 #ifndef U_HIDE_DRAFT_API
 245     /**
 246      * Formats a list of strings to a FormattedList, which exposes field
 247      * position information. The FormattedList contains more information than
 248      * a FieldPositionIterator.
 249      *
 250      * @param items     An array of strings to be combined and formatted.
 251      * @param n_items   Length of the array items.
 252      * @param errorCode ICU error code returned here.
 253      * @return          A FormattedList containing field information.
 254      * @draft ICU 64
 255      */
 256     FormattedList formatStringsToValue(
 257         const UnicodeString items[],
 258         int32_t n_items,
 259         UErrorCode& errorCode) const;
 260 #endif  /* U_HIDE_DRAFT_API */
 261 #endif // !UCONFIG_NO_FORMATTING
 262
 263 #ifndef U_HIDE_INTERNAL_API
 264     /**
 265       @internal for MeasureFormat
 266     */
 267     UnicodeString& format(
 268             const UnicodeString items[],
 269             int32_t n_items,
 270             UnicodeString& appendTo,
 271             int32_t index,
 272             int32_t &offset,
 273             UErrorCode& errorCode) const;
 274     /**
 275      * @internal constructor made public for testing.
 276      */
 277     ListFormatter(const ListFormatData &data, UErrorCode &errorCode);
 278     /**
 279      * @internal constructor made public for testing.
 280      */
 281     ListFormatter(const ListFormatInternal* listFormatterInternal);
 282 #endif  /* U_HIDE_INTERNAL_API */
 283
 284   private:
 285     static void initializeHash(UErrorCode& errorCode);
 286     static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode);
 287     struct ListPatternsSink;
 288     static ListFormatInternal* loadListFormatInternal(const Locale& locale, const char* style, UErrorCode& errorCode);
 289
 290     UnicodeString& format_(
 291         const UnicodeString items[], int32_t n_items, UnicodeString& appendTo,
 292         int32_t index, int32_t &offset, FieldPositionHandler* handler, UErrorCode& errorCode) const;
 293
 294     ListFormatter();
 295
 296     ListFormatInternal* owned;
 297     const ListFormatInternal* data;
 298 };
 299
 300 U_NAMESPACE_END
 301 #endif // U_SHOW_CPLUSPLUS_API
 302
 303 #endif // __LISTFORMATTER_H__