1 // © 2018 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html#License 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 15 #ifndef U_HIDE_DRAFT_API 16 /** 17 * \file 18 * \brief C++ API: Builder API for Locale 19 */ 20 21 U_NAMESPACE_BEGIN 22 class CharString; 23 24 /** 25 * <code>LocaleBuilder</code> is used to build instances of <code>Locale</code> 26 * from values configured by the setters. Unlike the <code>Locale</code> 27 * constructors, the <code>LocaleBuilder</code> checks if a value configured by a 28 * setter satisfies the syntax requirements defined by the <code>Locale</code> 29 * class. A <code>Locale</code> object created by a <code>LocaleBuilder</code> is 30 * well-formed and can be transformed to a well-formed IETF BCP 47 language tag 31 * without losing information. 32 * 33 * <p>The following example shows how to create a <code>Locale</code> object 34 * with the <code>LocaleBuilder</code>. 35 * <blockquote> 36 * <pre> 37 * UErrorCode status = U_ZERO_ERROR; 38 * Locale aLocale = LocaleBuilder() 39 * .setLanguage("sr") 40 * .setScript("Latn") 41 * .setRegion("RS") 42 * .build(status); 43 * if (U_SUCCESS(status)) { 44 * // ... 45 * } 46 * </pre> 47 * </blockquote> 48 * 49 * <p>LocaleBuilders can be reused; <code>clear()</code> resets all 50 * fields to their default values. 51 * 52 * <p>LocaleBuilder tracks errors in an internal UErrorCode. For all setters, 53 * except setLanguageTag and setLocale, LocaleBuilder will return immediately 54 * if the internal UErrorCode is in error state. 55 * To reset internal state and error code, call clear method. 56 * The setLanguageTag and setLocale method will first clear the internal 57 * UErrorCode, then track the error of the validation of the input parameter 58 * into the internal UErrorCode. 59 * 60 * @draft ICU 64 61 */ 62 class U_COMMON_API LocaleBuilder : public UObject { 63 public: 64 /** 65 * Constructs an empty LocaleBuilder. The default value of all 66 * fields, extensions, and private use information is the 67 * empty string. 68 * 69 * @draft ICU 64 70 */ 71 LocaleBuilder(); 72 73 /** 74 * Destructor 75 * @draft ICU 64 76 */ 77 virtual ~LocaleBuilder(); 78 79 /** 80 * Resets the <code>LocaleBuilder</code> to match the provided 81 * <code>locale</code>. Existing state is discarded. 82 * 83 * <p>All fields of the locale must be well-formed. 84 * <p>This method clears the internal UErrorCode. 85 * 86 * @param locale the locale 87 * @return This builder. 88 * 89 * @draft ICU 64 90 */ 91 LocaleBuilder& setLocale(const Locale& locale); 92 93 /** 94 * Resets the LocaleBuilder to match the provided 95 * [Unicode Locale Identifier](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id) . 96 * Discards the existing state. the empty string cause the builder to be 97 * reset, like {@link #clear}. Grandfathered tags are converted to their 98 * canonical form before being processed. Otherwise, the <code>language 99 * tag</code> must be well-formed, or else the build() method will later 100 * report an U_ILLEGAL_ARGUMENT_ERROR. 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. 107 * @draft ICU 64 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. 122 * @draft ICU 64 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. 138 * @draft ICU 64 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. 157 * @draft ICU 64 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. 178 * @draft ICU 64 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. 199 * @draft ICU 64 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. 219 * @draft ICU 64 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. 232 * @draft ICU 64 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. 245 * @draft ICU 64 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 254 * @draft ICU 64 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 263 * @draft ICU 64 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 278 * @draft ICU 64 279 */ 280 Locale build(UErrorCode& status); 281 282 #ifndef U_HIDE_DRAFT_API 283 /** 284 * Sets the UErrorCode if an error occurred while recording sets. 285 * Preserves older error codes in the outErrorCode. 286 * @param outErrorCode Set to an error code that occurred while setting subtags. 287 * Unchanged if there is no such error or if outErrorCode 288 * already contained an error. 289 * @return TRUE if U_FAILURE(outErrorCode) 290 * @draft ICU 65 291 */ 292 UBool copyErrorTo(UErrorCode &outErrorCode) const; 293 #endif /* U_HIDE_DRAFT_API */ 294 295 private: 296 friend class LocaleMatcher::Result; 297 298 void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode); 299 300 UErrorCode status_; 301 char language_[9]; 302 char script_[5]; 303 char region_[4]; 304 CharString *variant_; // Pointer not object so we need not #include internal charstr.h. 305 icu::Locale *extensions_; // Pointer not object. Storage for all other fields. 306 307 }; 308 309 U_NAMESPACE_END 310 311 #endif // U_HIDE_DRAFT_API 312 313 #endif /* U_SHOW_CPLUSPLUS_API */ 314 315 #endif // __LOCALEBUILDER_H__ 316