include/unicode/localebuilder.h

0001 // © 2018 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 #ifndef __LOCALEBUILDER_H__
0004 #define __LOCALEBUILDER_H__
0005
0006 #include "unicode/utypes.h"
0007
0008 #if U_SHOW_CPLUSPLUS_API
0009
0010 #include "unicode/locid.h"
0011 #include "unicode/localematcher.h"
0012 #include "unicode/stringpiece.h"
0013 #include "unicode/uobject.h"
0014
0015 /**
0016  * \file
0017  * \brief C++ API: Builder API for Locale
0018  */
0019
0020 U_NAMESPACE_BEGIN
0021 class CharString;
0022
0023 /**
0024  * <code>LocaleBuilder</code> is used to build instances of <code>Locale</code>
0025  * from values configured by the setters.  Unlike the <code>Locale</code>
0026  * constructors, the <code>LocaleBuilder</code> checks if a value configured by a
0027  * setter satisfies the syntax requirements defined by the <code>Locale</code>
0028  * class.  A <code>Locale</code> object created by a <code>LocaleBuilder</code> is
0029  * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
0030  * without losing information.
0031  *
0032  * <p>The following example shows how to create a <code>Locale</code> object
0033  * with the <code>LocaleBuilder</code>.
0034  * <blockquote>
0035  * <pre>
0036  *     UErrorCode status = U_ZERO_ERROR;
0037  *     Locale aLocale = LocaleBuilder()
0038  *                          .setLanguage("sr")
0039  *                          .setScript("Latn")
0040  *                          .setRegion("RS")
0041  *                          .build(status);
0042  *     if (U_SUCCESS(status)) {
0043  *       // ...
0044  *     }
0045  * </pre>
0046  * </blockquote>
0047  *
0048  * <p>LocaleBuilders can be reused; <code>clear()</code> resets all
0049  * fields to their default values.
0050  *
0051  * <p>LocaleBuilder tracks errors in an internal UErrorCode. For all setters,
0052  * except setLanguageTag and setLocale, LocaleBuilder will return immediately
0053  * if the internal UErrorCode is in error state.
0054  * To reset internal state and error code, call clear method.
0055  * The setLanguageTag and setLocale method will first clear the internal
0056  * UErrorCode, then track the error of the validation of the input parameter
0057  * into the internal UErrorCode.
0058  *
0059  * @stable ICU 64
0060  */
0061 class U_COMMON_API LocaleBuilder : public UObject {
0062 public:
0063     /**
0064      * Constructs an empty LocaleBuilder. The default value of all
0065      * fields, extensions, and private use information is the
0066      * empty string.
0067      *
0068      * @stable ICU 64
0069      */
0070     LocaleBuilder();
0071
0072     /**
0073      * Destructor
0074      * @stable ICU 64
0075      */
0076     virtual ~LocaleBuilder();
0077
0078     /**
0079      * Resets the <code>LocaleBuilder</code> to match the provided
0080      * <code>locale</code>.  Existing state is discarded.
0081      *
0082      * <p>All fields of the locale must be well-formed.
0083      * <p>This method clears the internal UErrorCode.
0084      *
0085      * @param locale the locale
0086      * @return This builder.
0087      *
0088      * @stable ICU 64
0089      */
0090     LocaleBuilder& setLocale(const Locale& locale);
0091
0092     /**
0093      * Resets the LocaleBuilder to match the provided IETF BCP 47 language tag.
0094      * Discards the existing state.
0095      * The empty string causes the builder to be reset, like {@link #clear}.
0096      * Legacy language tags (marked as “Type: grandfathered” in BCP 47)
0097      * are converted to their canonical form before being processed.
0098      * Otherwise, the <code>language tag</code> must be well-formed,
0099      * or else the build() method will later report an U_ILLEGAL_ARGUMENT_ERROR.
0100      *
0101      * <p>This method clears the internal UErrorCode.
0102      *
0103      * @param tag the language tag, defined as IETF BCP 47 language tag.
0104      * @return This builder.
0105      * @stable ICU 64
0106      */
0107     LocaleBuilder& setLanguageTag(StringPiece tag);
0108
0109     /**
0110      * Sets the language.  If <code>language</code> is the empty string, the
0111      * language in this <code>LocaleBuilder</code> is removed. Otherwise, the
0112      * <code>language</code> must be well-formed, or else the build() method will
0113      * later report an U_ILLEGAL_ARGUMENT_ERROR.
0114      *
0115      * <p>The syntax of language value is defined as
0116      * [unicode_language_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_language_subtag).
0117      *
0118      * @param language the language
0119      * @return This builder.
0120      * @stable ICU 64
0121      */
0122     LocaleBuilder& setLanguage(StringPiece language);
0123
0124     /**
0125      * Sets the script. If <code>script</code> is the empty string, the script in
0126      * this <code>LocaleBuilder</code> is removed.
0127      * Otherwise, the <code>script</code> must be well-formed, or else the build()
0128      * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
0129      *
0130      * <p>The script value is a four-letter script code as
0131      * [unicode_script_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_script_subtag)
0132      * defined by ISO 15924
0133      *
0134      * @param script the script
0135      * @return This builder.
0136      * @stable ICU 64
0137      */
0138     LocaleBuilder& setScript(StringPiece script);
0139
0140     /**
0141      * Sets the region.  If region is the empty string, the region in this
0142      * <code>LocaleBuilder</code> is removed. Otherwise, the <code>region</code>
0143      * must be well-formed, or else the build() method will later report an
0144      * U_ILLEGAL_ARGUMENT_ERROR.
0145      *
0146      * <p>The region value is defined by
0147      *  [unicode_region_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_region_subtag)
0148      * as a two-letter ISO 3166 code or a three-digit UN M.49 area code.
0149      *
0150      * <p>The region value in the <code>Locale</code> created by the
0151      * <code>LocaleBuilder</code> is always normalized to upper case.
0152      *
0153      * @param region the region
0154      * @return This builder.
0155      * @stable ICU 64
0156      */
0157     LocaleBuilder& setRegion(StringPiece region);
0158
0159     /**
0160      * Sets the variant.  If variant is the empty string, the variant in this
0161      * <code>LocaleBuilder</code> is removed.  Otherwise, the <code>variant</code>
0162      * must be well-formed, or else the build() method will later report an
0163      * U_ILLEGAL_ARGUMENT_ERROR.
0164      *
0165      * <p><b>Note:</b> This method checks if <code>variant</code>
0166      * satisfies the
0167      * [unicode_variant_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_variant_subtag)
0168      * syntax requirements, and normalizes the value to lowercase letters. However,
0169      * the <code>Locale</code> class does not impose any syntactic
0170      * restriction on variant. To set an ill-formed variant, use a Locale constructor.
0171      * If there are multiple unicode_variant_subtag, the caller must concatenate
0172      * them with '-' as separator (ex: "foobar-fibar").
0173      *
0174      * @param variant the variant
0175      * @return This builder.
0176      * @stable ICU 64
0177      */
0178     LocaleBuilder& setVariant(StringPiece variant);
0179
0180     /**
0181      * Sets the extension for the given key. If the value is the empty string,
0182      * the extension is removed.  Otherwise, the <code>key</code> and
0183      * <code>value</code> must be well-formed, or else the build() method will
0184      * later report an U_ILLEGAL_ARGUMENT_ERROR.
0185      *
0186      * <p><b>Note:</b> The key ('u') is used for the Unicode locale extension.
0187      * Setting a value for this key replaces any existing Unicode locale key/type
0188      * pairs with those defined in the extension.
0189      *
0190      * <p><b>Note:</b> The key ('x') is used for the private use code. To be
0191      * well-formed, the value for this key needs only to have subtags of one to
0192      * eight alphanumeric characters, not two to eight as in the general case.
0193      *
0194      * @param key the extension key
0195      * @param value the extension value
0196      * @return This builder.
0197      * @stable ICU 64
0198      */
0199     LocaleBuilder& setExtension(char key, StringPiece value);
0200
0201     /**
0202      * Sets the Unicode locale keyword type for the given key. If the type
0203      * StringPiece is constructed with a nullptr, the keyword is removed.
0204      * If the type is the empty string, the keyword is set without type subtags.
0205      * Otherwise, the key and type must be well-formed, or else the build()
0206      * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
0207      *
0208      * <p>Keys and types are converted to lower case.
0209      *
0210      * <p><b>Note</b>:Setting the 'u' extension via {@link #setExtension}
0211      * replaces all Unicode locale keywords with those defined in the
0212      * extension.
0213      *
0214      * @param key the Unicode locale key
0215      * @param type the Unicode locale type
0216      * @return This builder.
0217      * @stable ICU 64
0218      */
0219     LocaleBuilder& setUnicodeLocaleKeyword(
0220         StringPiece key, StringPiece type);
0221
0222     /**
0223      * Adds a unicode locale attribute, if not already present, otherwise
0224      * has no effect.  The attribute must not be empty string and must be
0225      * well-formed or U_ILLEGAL_ARGUMENT_ERROR will be set to status
0226      * during the build() call.
0227      *
0228      * @param attribute the attribute
0229      * @return This builder.
0230      * @stable ICU 64
0231      */
0232     LocaleBuilder& addUnicodeLocaleAttribute(StringPiece attribute);
0233
0234     /**
0235      * Removes a unicode locale attribute, if present, otherwise has no
0236      * effect.  The attribute must not be empty string and must be well-formed
0237      * or U_ILLEGAL_ARGUMENT_ERROR will be set to status during the build() call.
0238      *
0239      * <p>Attribute comparison for removal is case-insensitive.
0240      *
0241      * @param attribute the attribute
0242      * @return This builder.
0243      * @stable ICU 64
0244      */
0245     LocaleBuilder& removeUnicodeLocaleAttribute(StringPiece attribute);
0246
0247     /**
0248      * Resets the builder to its initial, empty state.
0249      * <p>This method clears the internal UErrorCode.
0250      *
0251      * @return this builder
0252      * @stable ICU 64
0253      */
0254     LocaleBuilder& clear();
0255
0256     /**
0257      * Resets the extensions to their initial, empty state.
0258      * Language, script, region and variant are unchanged.
0259      *
0260      * @return this builder
0261      * @stable ICU 64
0262      */
0263     LocaleBuilder& clearExtensions();
0264
0265     /**
0266      * Returns an instance of <code>Locale</code> created from the fields set
0267      * on this builder.
0268      * If any set methods or during the build() call require memory allocation
0269      * but fail U_MEMORY_ALLOCATION_ERROR will be set to status.
0270      * If any of the fields set by the setters are not well-formed, the status
0271      * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will
0272      * not change after the build() call and the caller is free to keep using
0273      * the same builder to build more locales.
0274      *
0275      * @return a new Locale
0276      * @stable ICU 64
0277      */
0278     Locale build(UErrorCode& status);
0279
0280     /**
0281      * Sets the UErrorCode if an error occurred while recording sets.
0282      * Preserves older error codes in the outErrorCode.
0283      * @param outErrorCode Set to an error code that occurred while setting subtags.
0284      *                  Unchanged if there is no such error or if outErrorCode
0285      *                  already contained an error.
0286      * @return true if U_FAILURE(outErrorCode)
0287      * @stable ICU 65
0288      */
0289     UBool copyErrorTo(UErrorCode &outErrorCode) const;
0290
0291 private:
0292     friend class LocaleMatcher::Result;
0293
0294     void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode);
0295
0296     UErrorCode status_;
0297     char language_[9];
0298     char script_[5];
0299     char region_[4];
0300     CharString *variant_;  // Pointer not object so we need not #include internal charstr.h.
0301     icu::Locale *extensions_;  // Pointer not object. Storage for all other fields.
0302
0303 };
0304
0305 U_NAMESPACE_END
0306
0307 #endif /* U_SHOW_CPLUSPLUS_API */
0308
0309 #endif  // __LOCALEBUILDER_H__