LocaleBuilder is used to build instances of Locale
jpayne@69: * from values configured by the setters. Unlike the Locale
jpayne@69: * constructors, the LocaleBuilder checks if a value configured by a
jpayne@69: * setter satisfies the syntax requirements defined by the Locale
jpayne@69: * class. A Locale object created by a LocaleBuilder is
jpayne@69: * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
jpayne@69: * without losing information.
jpayne@69: *
jpayne@69: * The following example shows how to create a Locale object
jpayne@69: * with the LocaleBuilder.
jpayne@69: *
jpayne@69: *
jpayne@69: * UErrorCode status = U_ZERO_ERROR;
jpayne@69: * Locale aLocale = LocaleBuilder()
jpayne@69: * .setLanguage("sr")
jpayne@69: * .setScript("Latn")
jpayne@69: * .setRegion("RS")
jpayne@69: * .build(status);
jpayne@69: * if (U_SUCCESS(status)) {
jpayne@69: * // ...
jpayne@69: * }
jpayne@69: *
jpayne@69: *
jpayne@69: *
jpayne@69: * LocaleBuilders can be reused; clear() resets all
jpayne@69: * fields to their default values.
jpayne@69: *
jpayne@69: *
LocaleBuilder tracks errors in an internal UErrorCode. For all setters,
jpayne@69: * except setLanguageTag and setLocale, LocaleBuilder will return immediately
jpayne@69: * if the internal UErrorCode is in error state.
jpayne@69: * To reset internal state and error code, call clear method.
jpayne@69: * The setLanguageTag and setLocale method will first clear the internal
jpayne@69: * UErrorCode, then track the error of the validation of the input parameter
jpayne@69: * into the internal UErrorCode.
jpayne@69: *
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: class U_COMMON_API LocaleBuilder : public UObject {
jpayne@69: public:
jpayne@69: /**
jpayne@69: * Constructs an empty LocaleBuilder. The default value of all
jpayne@69: * fields, extensions, and private use information is the
jpayne@69: * empty string.
jpayne@69: *
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder();
jpayne@69:
jpayne@69: /**
jpayne@69: * Destructor
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: virtual ~LocaleBuilder();
jpayne@69:
jpayne@69: /**
jpayne@69: * Resets the LocaleBuilder to match the provided
jpayne@69: * locale. Existing state is discarded.
jpayne@69: *
jpayne@69: *
All fields of the locale must be well-formed. jpayne@69: *
This method clears the internal UErrorCode.
jpayne@69: *
jpayne@69: * @param locale the locale
jpayne@69: * @return This builder.
jpayne@69: *
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& setLocale(const Locale& locale);
jpayne@69:
jpayne@69: /**
jpayne@69: * Resets the LocaleBuilder to match the provided
jpayne@69: * [Unicode Locale Identifier](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id) .
jpayne@69: * Discards the existing state. the empty string cause the builder to be
jpayne@69: * reset, like {@link #clear}. Grandfathered tags are converted to their
jpayne@69: * canonical form before being processed. Otherwise, the language
jpayne@69: * tag must be well-formed, or else the build() method will later
jpayne@69: * report an U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69: *
jpayne@69: *
This method clears the internal UErrorCode.
jpayne@69: *
jpayne@69: * @param tag the language tag, defined as
jpayne@69: * [unicode_locale_id](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id).
jpayne@69: * @return This builder.
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& setLanguageTag(StringPiece tag);
jpayne@69:
jpayne@69: /**
jpayne@69: * Sets the language. If language is the empty string, the
jpayne@69: * language in this LocaleBuilder is removed. Otherwise, the
jpayne@69: * language must be well-formed, or else the build() method will
jpayne@69: * later report an U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69: *
jpayne@69: *
The syntax of language value is defined as
jpayne@69: * [unicode_language_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_language_subtag).
jpayne@69: *
jpayne@69: * @param language the language
jpayne@69: * @return This builder.
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& setLanguage(StringPiece language);
jpayne@69:
jpayne@69: /**
jpayne@69: * Sets the script. If script is the empty string, the script in
jpayne@69: * this LocaleBuilder is removed.
jpayne@69: * Otherwise, the script must be well-formed, or else the build()
jpayne@69: * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69: *
jpayne@69: *
The script value is a four-letter script code as
jpayne@69: * [unicode_script_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_script_subtag)
jpayne@69: * defined by ISO 15924
jpayne@69: *
jpayne@69: * @param script the script
jpayne@69: * @return This builder.
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& setScript(StringPiece script);
jpayne@69:
jpayne@69: /**
jpayne@69: * Sets the region. If region is the empty string, the region in this
jpayne@69: * LocaleBuilder is removed. Otherwise, the region
jpayne@69: * must be well-formed, or else the build() method will later report an
jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69: *
jpayne@69: *
The region value is defined by jpayne@69: * [unicode_region_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_region_subtag) jpayne@69: * as a two-letter ISO 3166 code or a three-digit UN M.49 area code. jpayne@69: * jpayne@69: *
The region value in the Locale created by the
jpayne@69: * LocaleBuilder is always normalized to upper case.
jpayne@69: *
jpayne@69: * @param region the region
jpayne@69: * @return This builder.
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& setRegion(StringPiece region);
jpayne@69:
jpayne@69: /**
jpayne@69: * Sets the variant. If variant is the empty string, the variant in this
jpayne@69: * LocaleBuilder is removed. Otherwise, the variant
jpayne@69: * must be well-formed, or else the build() method will later report an
jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69: *
jpayne@69: *
Note: This method checks if variant
jpayne@69: * satisfies the
jpayne@69: * [unicode_variant_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_variant_subtag)
jpayne@69: * syntax requirements, and normalizes the value to lowercase letters. However,
jpayne@69: * the Locale class does not impose any syntactic
jpayne@69: * restriction on variant. To set an ill-formed variant, use a Locale constructor.
jpayne@69: * If there are multiple unicode_variant_subtag, the caller must concatenate
jpayne@69: * them with '-' as separator (ex: "foobar-fibar").
jpayne@69: *
jpayne@69: * @param variant the variant
jpayne@69: * @return This builder.
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& setVariant(StringPiece variant);
jpayne@69:
jpayne@69: /**
jpayne@69: * Sets the extension for the given key. If the value is the empty string,
jpayne@69: * the extension is removed. Otherwise, the key and
jpayne@69: * value must be well-formed, or else the build() method will
jpayne@69: * later report an U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69: *
jpayne@69: *
Note: The key ('u') is used for the Unicode locale extension. jpayne@69: * Setting a value for this key replaces any existing Unicode locale key/type jpayne@69: * pairs with those defined in the extension. jpayne@69: * jpayne@69: *
Note: The key ('x') is used for the private use code. To be jpayne@69: * well-formed, the value for this key needs only to have subtags of one to jpayne@69: * eight alphanumeric characters, not two to eight as in the general case. jpayne@69: * jpayne@69: * @param key the extension key jpayne@69: * @param value the extension value jpayne@69: * @return This builder. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: LocaleBuilder& setExtension(char key, StringPiece value); jpayne@69: jpayne@69: /** jpayne@69: * Sets the Unicode locale keyword type for the given key. If the type jpayne@69: * StringPiece is constructed with a nullptr, the keyword is removed. jpayne@69: * If the type is the empty string, the keyword is set without type subtags. jpayne@69: * Otherwise, the key and type must be well-formed, or else the build() jpayne@69: * method will later report an U_ILLEGAL_ARGUMENT_ERROR. jpayne@69: * jpayne@69: *
Keys and types are converted to lower case. jpayne@69: * jpayne@69: *
Note:Setting the 'u' extension via {@link #setExtension} jpayne@69: * replaces all Unicode locale keywords with those defined in the jpayne@69: * extension. jpayne@69: * jpayne@69: * @param key the Unicode locale key jpayne@69: * @param type the Unicode locale type jpayne@69: * @return This builder. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: LocaleBuilder& setUnicodeLocaleKeyword( jpayne@69: StringPiece key, StringPiece type); jpayne@69: jpayne@69: /** jpayne@69: * Adds a unicode locale attribute, if not already present, otherwise jpayne@69: * has no effect. The attribute must not be empty string and must be jpayne@69: * well-formed or U_ILLEGAL_ARGUMENT_ERROR will be set to status jpayne@69: * during the build() call. jpayne@69: * jpayne@69: * @param attribute the attribute jpayne@69: * @return This builder. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: LocaleBuilder& addUnicodeLocaleAttribute(StringPiece attribute); jpayne@69: jpayne@69: /** jpayne@69: * Removes a unicode locale attribute, if present, otherwise has no jpayne@69: * effect. The attribute must not be empty string and must be well-formed jpayne@69: * or U_ILLEGAL_ARGUMENT_ERROR will be set to status during the build() call. jpayne@69: * jpayne@69: *
Attribute comparison for removal is case-insensitive. jpayne@69: * jpayne@69: * @param attribute the attribute jpayne@69: * @return This builder. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: LocaleBuilder& removeUnicodeLocaleAttribute(StringPiece attribute); jpayne@69: jpayne@69: /** jpayne@69: * Resets the builder to its initial, empty state. jpayne@69: *
This method clears the internal UErrorCode.
jpayne@69: *
jpayne@69: * @return this builder
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& clear();
jpayne@69:
jpayne@69: /**
jpayne@69: * Resets the extensions to their initial, empty state.
jpayne@69: * Language, script, region and variant are unchanged.
jpayne@69: *
jpayne@69: * @return this builder
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: LocaleBuilder& clearExtensions();
jpayne@69:
jpayne@69: /**
jpayne@69: * Returns an instance of Locale created from the fields set
jpayne@69: * on this builder.
jpayne@69: * If any set methods or during the build() call require memory allocation
jpayne@69: * but fail U_MEMORY_ALLOCATION_ERROR will be set to status.
jpayne@69: * If any of the fields set by the setters are not well-formed, the status
jpayne@69: * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will
jpayne@69: * not change after the build() call and the caller is free to keep using
jpayne@69: * the same builder to build more locales.
jpayne@69: *
jpayne@69: * @return a new Locale
jpayne@69: * @stable ICU 64
jpayne@69: */
jpayne@69: Locale build(UErrorCode& status);
jpayne@69:
jpayne@69: #ifndef U_HIDE_DRAFT_API
jpayne@69: /**
jpayne@69: * Sets the UErrorCode if an error occurred while recording sets.
jpayne@69: * Preserves older error codes in the outErrorCode.
jpayne@69: * @param outErrorCode Set to an error code that occurred while setting subtags.
jpayne@69: * Unchanged if there is no such error or if outErrorCode
jpayne@69: * already contained an error.
jpayne@69: * @return TRUE if U_FAILURE(outErrorCode)
jpayne@69: * @draft ICU 65
jpayne@69: */
jpayne@69: UBool copyErrorTo(UErrorCode &outErrorCode) const;
jpayne@69: #endif /* U_HIDE_DRAFT_API */
jpayne@69:
jpayne@69: private:
jpayne@69: friend class LocaleMatcher::Result;
jpayne@69:
jpayne@69: void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode);
jpayne@69:
jpayne@69: UErrorCode status_;
jpayne@69: char language_[9];
jpayne@69: char script_[5];
jpayne@69: char region_[4];
jpayne@69: CharString *variant_; // Pointer not object so we need not #include internal charstr.h.
jpayne@69: icu::Locale *extensions_; // Pointer not object. Storage for all other fields.
jpayne@69:
jpayne@69: };
jpayne@69:
jpayne@69: U_NAMESPACE_END
jpayne@69:
jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69:
jpayne@69: #endif // __LOCALEBUILDER_H__