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