Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1 | // © 2018 and later: Unicode, Inc. and others. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 2 | // License & terms of use: http://www.unicode.org/copyright.html |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 3 | #ifndef __LOCALEBUILDER_H__ |
| 4 | #define __LOCALEBUILDER_H__ |
| 5 | |
| 6 | #include "unicode/utypes.h" |
| 7 | |
| 8 | #if U_SHOW_CPLUSPLUS_API |
| 9 | |
| 10 | #include "unicode/locid.h" |
| 11 | #include "unicode/localematcher.h" |
| 12 | #include "unicode/stringpiece.h" |
| 13 | #include "unicode/uobject.h" |
| 14 | |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 15 | /** |
| 16 | * \file |
| 17 | * \brief C++ API: Builder API for Locale |
| 18 | */ |
| 19 | |
| 20 | U_NAMESPACE_BEGIN |
| 21 | class CharString; |
| 22 | |
| 23 | /** |
| 24 | * <code>LocaleBuilder</code> is used to build instances of <code>Locale</code> |
| 25 | * from values configured by the setters. Unlike the <code>Locale</code> |
| 26 | * constructors, the <code>LocaleBuilder</code> checks if a value configured by a |
| 27 | * setter satisfies the syntax requirements defined by the <code>Locale</code> |
| 28 | * class. A <code>Locale</code> object created by a <code>LocaleBuilder</code> is |
| 29 | * well-formed and can be transformed to a well-formed IETF BCP 47 language tag |
| 30 | * without losing information. |
| 31 | * |
| 32 | * <p>The following example shows how to create a <code>Locale</code> object |
| 33 | * with the <code>LocaleBuilder</code>. |
| 34 | * <blockquote> |
| 35 | * <pre> |
| 36 | * UErrorCode status = U_ZERO_ERROR; |
| 37 | * Locale aLocale = LocaleBuilder() |
| 38 | * .setLanguage("sr") |
| 39 | * .setScript("Latn") |
| 40 | * .setRegion("RS") |
| 41 | * .build(status); |
| 42 | * if (U_SUCCESS(status)) { |
| 43 | * // ... |
| 44 | * } |
| 45 | * </pre> |
| 46 | * </blockquote> |
| 47 | * |
| 48 | * <p>LocaleBuilders can be reused; <code>clear()</code> resets all |
| 49 | * fields to their default values. |
| 50 | * |
| 51 | * <p>LocaleBuilder tracks errors in an internal UErrorCode. For all setters, |
| 52 | * except setLanguageTag and setLocale, LocaleBuilder will return immediately |
| 53 | * if the internal UErrorCode is in error state. |
| 54 | * To reset internal state and error code, call clear method. |
| 55 | * The setLanguageTag and setLocale method will first clear the internal |
| 56 | * UErrorCode, then track the error of the validation of the input parameter |
| 57 | * into the internal UErrorCode. |
| 58 | * |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 59 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 60 | */ |
| 61 | class U_COMMON_API LocaleBuilder : public UObject { |
| 62 | public: |
| 63 | /** |
| 64 | * Constructs an empty LocaleBuilder. The default value of all |
| 65 | * fields, extensions, and private use information is the |
| 66 | * empty string. |
| 67 | * |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 68 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 69 | */ |
| 70 | LocaleBuilder(); |
| 71 | |
| 72 | /** |
| 73 | * Destructor |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 74 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 75 | */ |
| 76 | virtual ~LocaleBuilder(); |
| 77 | |
| 78 | /** |
| 79 | * Resets the <code>LocaleBuilder</code> to match the provided |
| 80 | * <code>locale</code>. Existing state is discarded. |
| 81 | * |
| 82 | * <p>All fields of the locale must be well-formed. |
| 83 | * <p>This method clears the internal UErrorCode. |
| 84 | * |
| 85 | * @param locale the locale |
| 86 | * @return This builder. |
| 87 | * |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 88 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 89 | */ |
| 90 | LocaleBuilder& setLocale(const Locale& locale); |
| 91 | |
| 92 | /** |
| 93 | * Resets the LocaleBuilder to match the provided |
| 94 | * [Unicode Locale Identifier](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id) . |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 95 | * Discards the existing state. |
| 96 | * The empty string causes the builder to be reset, like {@link #clear}. |
| 97 | * Legacy language tags (marked as “Type: grandfathered” in BCP 47) |
| 98 | * are converted to their canonical form before being processed. |
| 99 | * Otherwise, the <code>language tag</code> must be well-formed, |
| 100 | * or else the build() method will later report an U_ILLEGAL_ARGUMENT_ERROR. |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 101 | * |
| 102 | * <p>This method clears the internal UErrorCode. |
| 103 | * |
| 104 | * @param tag the language tag, defined as |
| 105 | * [unicode_locale_id](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id). |
| 106 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 107 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 108 | */ |
| 109 | LocaleBuilder& setLanguageTag(StringPiece tag); |
| 110 | |
| 111 | /** |
| 112 | * Sets the language. If <code>language</code> is the empty string, the |
| 113 | * language in this <code>LocaleBuilder</code> is removed. Otherwise, the |
| 114 | * <code>language</code> must be well-formed, or else the build() method will |
| 115 | * later report an U_ILLEGAL_ARGUMENT_ERROR. |
| 116 | * |
| 117 | * <p>The syntax of language value is defined as |
| 118 | * [unicode_language_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_language_subtag). |
| 119 | * |
| 120 | * @param language the language |
| 121 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 122 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 123 | */ |
| 124 | LocaleBuilder& setLanguage(StringPiece language); |
| 125 | |
| 126 | /** |
| 127 | * Sets the script. If <code>script</code> is the empty string, the script in |
| 128 | * this <code>LocaleBuilder</code> is removed. |
| 129 | * Otherwise, the <code>script</code> must be well-formed, or else the build() |
| 130 | * method will later report an U_ILLEGAL_ARGUMENT_ERROR. |
| 131 | * |
| 132 | * <p>The script value is a four-letter script code as |
| 133 | * [unicode_script_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_script_subtag) |
| 134 | * defined by ISO 15924 |
| 135 | * |
| 136 | * @param script the script |
| 137 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 138 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 139 | */ |
| 140 | LocaleBuilder& setScript(StringPiece script); |
| 141 | |
| 142 | /** |
| 143 | * Sets the region. If region is the empty string, the region in this |
| 144 | * <code>LocaleBuilder</code> is removed. Otherwise, the <code>region</code> |
| 145 | * must be well-formed, or else the build() method will later report an |
| 146 | * U_ILLEGAL_ARGUMENT_ERROR. |
| 147 | * |
| 148 | * <p>The region value is defined by |
| 149 | * [unicode_region_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_region_subtag) |
| 150 | * as a two-letter ISO 3166 code or a three-digit UN M.49 area code. |
| 151 | * |
| 152 | * <p>The region value in the <code>Locale</code> created by the |
| 153 | * <code>LocaleBuilder</code> is always normalized to upper case. |
| 154 | * |
| 155 | * @param region the region |
| 156 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 157 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 158 | */ |
| 159 | LocaleBuilder& setRegion(StringPiece region); |
| 160 | |
| 161 | /** |
| 162 | * Sets the variant. If variant is the empty string, the variant in this |
| 163 | * <code>LocaleBuilder</code> is removed. Otherwise, the <code>variant</code> |
| 164 | * must be well-formed, or else the build() method will later report an |
| 165 | * U_ILLEGAL_ARGUMENT_ERROR. |
| 166 | * |
| 167 | * <p><b>Note:</b> This method checks if <code>variant</code> |
| 168 | * satisfies the |
| 169 | * [unicode_variant_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_variant_subtag) |
| 170 | * syntax requirements, and normalizes the value to lowercase letters. However, |
| 171 | * the <code>Locale</code> class does not impose any syntactic |
| 172 | * restriction on variant. To set an ill-formed variant, use a Locale constructor. |
| 173 | * If there are multiple unicode_variant_subtag, the caller must concatenate |
| 174 | * them with '-' as separator (ex: "foobar-fibar"). |
| 175 | * |
| 176 | * @param variant the variant |
| 177 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 178 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 179 | */ |
| 180 | LocaleBuilder& setVariant(StringPiece variant); |
| 181 | |
| 182 | /** |
| 183 | * Sets the extension for the given key. If the value is the empty string, |
| 184 | * the extension is removed. Otherwise, the <code>key</code> and |
| 185 | * <code>value</code> must be well-formed, or else the build() method will |
| 186 | * later report an U_ILLEGAL_ARGUMENT_ERROR. |
| 187 | * |
| 188 | * <p><b>Note:</b> The key ('u') is used for the Unicode locale extension. |
| 189 | * Setting a value for this key replaces any existing Unicode locale key/type |
| 190 | * pairs with those defined in the extension. |
| 191 | * |
| 192 | * <p><b>Note:</b> The key ('x') is used for the private use code. To be |
| 193 | * well-formed, the value for this key needs only to have subtags of one to |
| 194 | * eight alphanumeric characters, not two to eight as in the general case. |
| 195 | * |
| 196 | * @param key the extension key |
| 197 | * @param value the extension value |
| 198 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 199 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 200 | */ |
| 201 | LocaleBuilder& setExtension(char key, StringPiece value); |
| 202 | |
| 203 | /** |
| 204 | * Sets the Unicode locale keyword type for the given key. If the type |
| 205 | * StringPiece is constructed with a nullptr, the keyword is removed. |
| 206 | * If the type is the empty string, the keyword is set without type subtags. |
| 207 | * Otherwise, the key and type must be well-formed, or else the build() |
| 208 | * method will later report an U_ILLEGAL_ARGUMENT_ERROR. |
| 209 | * |
| 210 | * <p>Keys and types are converted to lower case. |
| 211 | * |
| 212 | * <p><b>Note</b>:Setting the 'u' extension via {@link #setExtension} |
| 213 | * replaces all Unicode locale keywords with those defined in the |
| 214 | * extension. |
| 215 | * |
| 216 | * @param key the Unicode locale key |
| 217 | * @param type the Unicode locale type |
| 218 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 219 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 220 | */ |
| 221 | LocaleBuilder& setUnicodeLocaleKeyword( |
| 222 | StringPiece key, StringPiece type); |
| 223 | |
| 224 | /** |
| 225 | * Adds a unicode locale attribute, if not already present, otherwise |
| 226 | * has no effect. The attribute must not be empty string and must be |
| 227 | * well-formed or U_ILLEGAL_ARGUMENT_ERROR will be set to status |
| 228 | * during the build() call. |
| 229 | * |
| 230 | * @param attribute the attribute |
| 231 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 232 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 233 | */ |
| 234 | LocaleBuilder& addUnicodeLocaleAttribute(StringPiece attribute); |
| 235 | |
| 236 | /** |
| 237 | * Removes a unicode locale attribute, if present, otherwise has no |
| 238 | * effect. The attribute must not be empty string and must be well-formed |
| 239 | * or U_ILLEGAL_ARGUMENT_ERROR will be set to status during the build() call. |
| 240 | * |
| 241 | * <p>Attribute comparison for removal is case-insensitive. |
| 242 | * |
| 243 | * @param attribute the attribute |
| 244 | * @return This builder. |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 245 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 246 | */ |
| 247 | LocaleBuilder& removeUnicodeLocaleAttribute(StringPiece attribute); |
| 248 | |
| 249 | /** |
| 250 | * Resets the builder to its initial, empty state. |
| 251 | * <p>This method clears the internal UErrorCode. |
| 252 | * |
| 253 | * @return this builder |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 254 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 255 | */ |
| 256 | LocaleBuilder& clear(); |
| 257 | |
| 258 | /** |
| 259 | * Resets the extensions to their initial, empty state. |
| 260 | * Language, script, region and variant are unchanged. |
| 261 | * |
| 262 | * @return this builder |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 263 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 264 | */ |
| 265 | LocaleBuilder& clearExtensions(); |
| 266 | |
| 267 | /** |
| 268 | * Returns an instance of <code>Locale</code> created from the fields set |
| 269 | * on this builder. |
| 270 | * If any set methods or during the build() call require memory allocation |
| 271 | * but fail U_MEMORY_ALLOCATION_ERROR will be set to status. |
| 272 | * If any of the fields set by the setters are not well-formed, the status |
| 273 | * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will |
| 274 | * not change after the build() call and the caller is free to keep using |
| 275 | * the same builder to build more locales. |
| 276 | * |
| 277 | * @return a new Locale |
Victor Chang | d8aa9d5 | 2021-01-05 23:49:57 +0000 | [diff] [blame] | 278 | * @stable ICU 64 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 279 | */ |
| 280 | Locale build(UErrorCode& status); |
| 281 | |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 282 | /** |
| 283 | * Sets the UErrorCode if an error occurred while recording sets. |
| 284 | * Preserves older error codes in the outErrorCode. |
| 285 | * @param outErrorCode Set to an error code that occurred while setting subtags. |
| 286 | * Unchanged if there is no such error or if outErrorCode |
| 287 | * already contained an error. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 288 | * @return true if U_FAILURE(outErrorCode) |
| 289 | * @stable ICU 65 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 290 | */ |
| 291 | UBool copyErrorTo(UErrorCode &outErrorCode) const; |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 292 | |
| 293 | private: |
| 294 | friend class LocaleMatcher::Result; |
| 295 | |
| 296 | void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode); |
| 297 | |
| 298 | UErrorCode status_; |
| 299 | char language_[9]; |
| 300 | char script_[5]; |
| 301 | char region_[4]; |
| 302 | CharString *variant_; // Pointer not object so we need not #include internal charstr.h. |
| 303 | icu::Locale *extensions_; // Pointer not object. Storage for all other fields. |
| 304 | |
| 305 | }; |
| 306 | |
| 307 | U_NAMESPACE_END |
| 308 | |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 309 | #endif /* U_SHOW_CPLUSPLUS_API */ |
| 310 | |
| 311 | #endif // __LOCALEBUILDER_H__ |