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