Back to home page

EIC code displayed by LXR

 
 

    


Warning, file /include/unicode/listformatter.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 *
0006 *   Copyright (C) 2012-2016, International Business Machines
0007 *   Corporation and others.  All Rights Reserved.
0008 *
0009 *******************************************************************************
0010 *   file name:  listformatter.h
0011 *   encoding:   UTF-8
0012 *   tab size:   8 (not used)
0013 *   indentation:4
0014 *
0015 *   created on: 20120426
0016 *   created by: Umesh P. Nair
0017 */
0018 
0019 #ifndef __LISTFORMATTER_H__
0020 #define __LISTFORMATTER_H__
0021 
0022 #include "unicode/utypes.h"
0023 
0024 #if U_SHOW_CPLUSPLUS_API
0025 
0026 #if !UCONFIG_NO_FORMATTING
0027 
0028 #include "unicode/unistr.h"
0029 #include "unicode/locid.h"
0030 #include "unicode/formattedvalue.h"
0031 #include "unicode/ulistformatter.h"
0032 
0033 U_NAMESPACE_BEGIN
0034 
0035 class FieldPositionHandler;
0036 class FormattedListData;
0037 class ListFormatter;
0038 
0039 /** @internal */
0040 class Hashtable;
0041 
0042 /** @internal */
0043 struct ListFormatInternal;
0044 
0045 /* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
0046 /**
0047  * @internal
0048  * \cond
0049  */
0050 struct ListFormatData : public UMemory {
0051     UnicodeString twoPattern;
0052     UnicodeString startPattern;
0053     UnicodeString middlePattern;
0054     UnicodeString endPattern;
0055     Locale locale;
0056 
0057   ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end,
0058                  const Locale& loc) :
0059       twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end), locale(loc) {}
0060 };
0061 /** \endcond */
0062 
0063 
0064 /**
0065  * \file
0066  * \brief C++ API: API for formatting a list.
0067  */
0068 
0069 
0070 /**
0071  * An immutable class containing the result of a list formatting operation.
0072  *
0073  * Instances of this class are immutable and thread-safe.
0074  *
0075  * When calling nextPosition():
0076  * The fields are returned from start to end. The special field category
0077  * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument
0078  * was inserted at the given position. The span category will
0079  * always occur before the corresponding instance of UFIELD_CATEGORY_LIST
0080  * in the nextPosition() iterator.
0081  *
0082  * Not intended for public subclassing.
0083  *
0084  * @stable ICU 64
0085  */
0086 class U_I18N_API FormattedList : public UMemory, public FormattedValue {
0087   public:
0088     /**
0089      * Default constructor; makes an empty FormattedList.
0090      * @stable ICU 64
0091      */
0092     FormattedList() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
0093 
0094     /**
0095      * Move constructor: Leaves the source FormattedList in an undefined state.
0096      * @stable ICU 64
0097      */
0098     FormattedList(FormattedList&& src) noexcept;
0099 
0100     /**
0101      * Destruct an instance of FormattedList.
0102      * @stable ICU 64
0103      */
0104     virtual ~FormattedList() override;
0105 
0106     /** Copying not supported; use move constructor instead. */
0107     FormattedList(const FormattedList&) = delete;
0108 
0109     /** Copying not supported; use move assignment instead. */
0110     FormattedList& operator=(const FormattedList&) = delete;
0111 
0112     /**
0113      * Move assignment: Leaves the source FormattedList in an undefined state.
0114      * @stable ICU 64
0115      */
0116     FormattedList& operator=(FormattedList&& src) noexcept;
0117 
0118     /** @copydoc FormattedValue::toString() */
0119     UnicodeString toString(UErrorCode& status) const override;
0120 
0121     /** @copydoc FormattedValue::toTempString() */
0122     UnicodeString toTempString(UErrorCode& status) const override;
0123 
0124     /** @copydoc FormattedValue::appendTo() */
0125     Appendable &appendTo(Appendable& appendable, UErrorCode& status) const override;
0126 
0127     /** @copydoc FormattedValue::nextPosition() */
0128     UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const override;
0129 
0130   private:
0131     FormattedListData *fData;
0132     UErrorCode fErrorCode;
0133     explicit FormattedList(FormattedListData *results)
0134         : fData(results), fErrorCode(U_ZERO_ERROR) {}
0135     explicit FormattedList(UErrorCode errorCode)
0136         : fData(nullptr), fErrorCode(errorCode) {}
0137     friend class ListFormatter;
0138 };
0139 
0140 
0141 /**
0142  * An immutable class for formatting a list, using data from CLDR (or supplied
0143  * separately).
0144  *
0145  * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
0146  * as "Alice, Bob, Charlie and Delta" in English.
0147  *
0148  * The ListFormatter class is not intended for public subclassing.
0149  * @stable ICU 50
0150  */
0151 class U_I18N_API ListFormatter : public UObject{
0152 
0153   public:
0154 
0155     /**
0156      * Copy constructor.
0157      * @stable ICU 52
0158      */
0159     ListFormatter(const ListFormatter&);
0160 
0161     /**
0162      * Assignment operator.
0163      * @stable ICU 52
0164      */
0165     ListFormatter& operator=(const ListFormatter& other);
0166 
0167     /**
0168      * Creates a ListFormatter appropriate for the default locale.
0169      *
0170      * @param errorCode ICU error code, set if no data available for default locale.
0171      * @return Pointer to a ListFormatter object for the default locale,
0172      *     created from internal data derived from CLDR data.
0173      * @stable ICU 50
0174      */
0175     static ListFormatter* createInstance(UErrorCode& errorCode);
0176 
0177     /**
0178      * Creates a ListFormatter appropriate for a locale.
0179      *
0180      * @param locale The locale.
0181      * @param errorCode ICU error code, set if no data available for the given locale.
0182      * @return A ListFormatter object created from internal data derived from
0183      *     CLDR data.
0184      * @stable ICU 50
0185      */
0186     static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode);
0187 
0188     /**
0189      * Creates a ListFormatter for the given locale, list type, and style.
0190      *
0191      * @param locale The locale.
0192      * @param type The type of list formatting to use.
0193      * @param width The width of formatting to use.
0194      * @param errorCode ICU error code, set if no data available for the given locale.
0195      * @return A ListFormatter object created from internal data derived from CLDR data.
0196      * @stable ICU 67
0197      */
0198     static ListFormatter* createInstance(
0199       const Locale& locale, UListFormatterType type, UListFormatterWidth width, UErrorCode& errorCode);
0200 
0201     /**
0202      * Destructor.
0203      *
0204      * @stable ICU 50
0205      */
0206     virtual ~ListFormatter();
0207 
0208 
0209     /**
0210      * Formats a list of strings.
0211      *
0212      * @param items An array of strings to be combined and formatted.
0213      * @param n_items Length of the array items.
0214      * @param appendTo The string to which the result should be appended to.
0215      * @param errorCode ICU error code, set if there is an error.
0216      * @return Formatted string combining the elements of items, appended to appendTo.
0217      * @stable ICU 50
0218      */
0219     UnicodeString& format(const UnicodeString items[], int32_t n_items,
0220         UnicodeString& appendTo, UErrorCode& errorCode) const;
0221 
0222     /**
0223      * Formats a list of strings to a FormattedList, which exposes field
0224      * position information. The FormattedList contains more information than
0225      * a FieldPositionIterator.
0226      *
0227      * @param items     An array of strings to be combined and formatted.
0228      * @param n_items   Length of the array items.
0229      * @param errorCode ICU error code returned here.
0230      * @return          A FormattedList containing field information.
0231      * @stable ICU 64
0232      */
0233     FormattedList formatStringsToValue(
0234         const UnicodeString items[],
0235         int32_t n_items,
0236         UErrorCode& errorCode) const;
0237 
0238 #ifndef U_HIDE_INTERNAL_API
0239     /**
0240       @internal for MeasureFormat
0241     */
0242     UnicodeString& format(
0243             const UnicodeString items[],
0244             int32_t n_items,
0245             UnicodeString& appendTo,
0246             int32_t index,
0247             int32_t &offset,
0248             UErrorCode& errorCode) const;
0249     /**
0250      * @internal constructor made public for testing.
0251      */
0252     ListFormatter(const ListFormatData &data, UErrorCode &errorCode);
0253     /**
0254      * @internal constructor made public for testing.
0255      */
0256     ListFormatter(const ListFormatInternal* listFormatterInternal);
0257 #endif  /* U_HIDE_INTERNAL_API */
0258 
0259   private:
0260   
0261     /**
0262      * Creates a ListFormatter appropriate for a locale and style.
0263      *
0264      * @param locale The locale.
0265      * @param style the style, either "standard", "or", "unit", "unit-narrow", or "unit-short"
0266      */
0267     static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode);
0268 
0269     static void initializeHash(UErrorCode& errorCode);
0270     static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode);
0271     struct U_HIDDEN ListPatternsSink;
0272     static ListFormatInternal* loadListFormatInternal(const Locale& locale, const char* style, UErrorCode& errorCode);
0273 
0274     ListFormatter() = delete;
0275 
0276     ListFormatInternal* owned;
0277     const ListFormatInternal* data;
0278 };
0279 
0280 U_NAMESPACE_END
0281 
0282 #endif /* #if !UCONFIG_NO_FORMATTING */
0283 
0284 #endif /* U_SHOW_CPLUSPLUS_API */
0285 
0286 #endif // __LISTFORMATTER_H__