ulocbuilder.h (17094B)
1 // © 2023 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 #ifndef __ULOCBUILDER_H__ 4 #define __ULOCBUILDER_H__ 5 6 #include "unicode/localpointer.h" 7 #include "unicode/ulocale.h" 8 #include "unicode/utypes.h" 9 10 /** 11 * \file 12 * \brief C API: Builder API for Locale 13 */ 14 15 /** 16 * Opaque C service object type for the locale builder API 17 * @stable ICU 74 18 */ 19 struct ULocaleBuilder; 20 21 /** 22 * C typedef for struct ULocaleBuilder. 23 * @stable ICU 74 24 */ 25 typedef struct ULocaleBuilder ULocaleBuilder; 26 27 /** 28 * <code>ULocaleBuilder</code> is used to build valid <code>locale</code> id 29 * string or IETF BCP 47 language tag from values configured by the setters. 30 * The <code>ULocaleBuilder</code> checks if a value configured by a 31 * setter satisfies the syntax requirements defined by the <code>Locale</code> 32 * class. A string of Locale created by a <code>ULocaleBuilder</code> is 33 * well-formed and can be transformed to a well-formed IETF BCP 47 language tag 34 * without losing information. 35 * 36 * <p>The following example shows how to create a <code>locale</code> string 37 * with the <code>ULocaleBuilder</code>. 38 * <blockquote> 39 * <pre> 40 * UErrorCode err = U_ZERO_ERROR; 41 * char buffer[ULOC_FULLNAME_CAPACITY]; 42 * ULocaleBuilder* builder = ulocbld_open(); 43 * ulocbld_setLanguage(builder, "sr", -1); 44 * ulocbld_setScript(builder, "Latn", -1); 45 * ulocbld_setRegion(builder, "RS", -1); 46 * int32_t length = ulocbld_buildLocaleID( 47 * builder, buffer, ULOC_FULLNAME_CAPACITY, &error); 48 * ulocbld_close(builder); 49 * </pre> 50 * </blockquote> 51 * 52 * <p>ULocaleBuilders can be reused; <code>ulocbld_clear()</code> resets all 53 * fields to their default values. 54 * 55 * <p>ULocaleBuilder tracks errors in an internal UErrorCode. For all setters, 56 * except ulocbld_setLanguageTag and ulocbld_setLocale, ULocaleBuilder will return immediately 57 * if the internal UErrorCode is in error state. 58 * To reset internal state and error code, call clear method. 59 * The ulocbld_setLanguageTag and setLocale method will first clear the internal 60 * UErrorCode, then track the error of the validation of the input parameter 61 * into the internal UErrorCode. 62 * 63 * @stable ICU 74 64 */ 65 66 /** 67 * Constructs an empty ULocaleBuilder. The default value of all 68 * fields, extensions, and private use information is the 69 * empty string. The created builder should be destroyed by calling 70 * ulocbld_close(); 71 * 72 * @stable ICU 74 73 */ 74 U_CAPI ULocaleBuilder* U_EXPORT2 75 ulocbld_open(void); 76 77 /** 78 * Close the builder and destroy it's internal states. 79 * @param builder the builder 80 * @stable ICU 74 81 */ 82 U_CAPI void U_EXPORT2 83 ulocbld_close(ULocaleBuilder* builder); 84 85 /** 86 * Resets the <code>ULocaleBuilder</code> to match the provided 87 * <code>locale</code>. Existing state is discarded. 88 * 89 * <p>All fields of the locale must be well-formed. 90 * <p>This method clears the internal UErrorCode. 91 * 92 * @param builder the builder 93 * @param locale the locale, a const char * pointer (need not be terminated when 94 * the length is non-negative) 95 * @param length the length of the locale; if negative, then the locale need to be 96 * null terminated, 97 * 98 * @stable ICU 74 99 */ 100 U_CAPI void U_EXPORT2 101 ulocbld_setLocale(ULocaleBuilder* builder, const char* locale, int32_t length); 102 103 /** 104 * Resets the <code>ULocaleBuilder</code> to match the provided 105 * <code>ULocale</code>. Existing state is discarded. 106 * 107 * <p>The locale must be not bogus. 108 * <p>This method clears the internal UErrorCode. 109 * 110 * @param builder the builder. 111 * @param locale the locale, a ULocale* pointer. The builder adopts the locale 112 * after the call and the client must not delete it. 113 * 114 * @stable ICU 74 115 */ 116 U_CAPI void U_EXPORT2 117 ulocbld_adoptULocale(ULocaleBuilder* builder, ULocale* locale); 118 119 /** 120 * Resets the ULocaleBuilder to match the provided IETF BCP 47 language tag. 121 * Discards the existing state. 122 * The empty string causes the builder to be reset, like {@link #ulocbld_clear}. 123 * Legacy language tags (marked as “Type: grandfathered” in BCP 47) 124 * are converted to their canonical form before being processed. 125 * Otherwise, the <code>language tag</code> must be well-formed, 126 * or else the ulocbld_buildLocaleID() and ulocbld_buildLanguageTag() methods 127 * will later report an U_ILLEGAL_ARGUMENT_ERROR. 128 * 129 * <p>This method clears the internal UErrorCode. 130 * 131 * @param builder the builder 132 * @param tag the language tag, defined as IETF BCP 47 language tag, a 133 * const char * pointer (need not be terminated when 134 * the length is non-negative) 135 * @param length the length of the tag; if negative, then the tag need to be 136 * null terminated, 137 * @stable ICU 74 138 */ 139 U_CAPI void U_EXPORT2 140 ulocbld_setLanguageTag(ULocaleBuilder* builder, const char* tag, int32_t length); 141 142 /** 143 * Sets the language. If <code>language</code> is the empty string, the 144 * language in this <code>ULocaleBuilder</code> is removed. Otherwise, the 145 * <code>language</code> must be well-formed, or else the ulocbld_buildLocaleID() 146 * and ulocbld_buildLanguageTag() methods will 147 * later report an U_ILLEGAL_ARGUMENT_ERROR. 148 * 149 * <p>The syntax of language value is defined as 150 * [unicode_language_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_language_subtag). 151 * 152 * @param builder the builder 153 * @param language the language, a const char * pointer (need not be terminated when 154 * the length is non-negative) 155 * @param length the length of the language; if negative, then the language need to be 156 * null terminated, 157 * @stable ICU 74 158 */ 159 U_CAPI void U_EXPORT2 160 ulocbld_setLanguage(ULocaleBuilder* builder, const char* language, int32_t length); 161 162 /** 163 * Sets the script. If <code>script</code> is the empty string, the script in 164 * this <code>ULocaleBuilder</code> is removed. 165 * Otherwise, the <code>script</code> must be well-formed, or else the 166 * ulocbld_buildLocaleID() and ulocbld_buildLanguageTag() methods will later 167 * report an U_ILLEGAL_ARGUMENT_ERROR. 168 * 169 * <p>The script value is a four-letter script code as 170 * [unicode_script_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_script_subtag) 171 * defined by ISO 15924 172 * 173 * @param builder the builder 174 * @param script the script, a const char * pointer (need not be terminated when 175 * the length is non-negative) 176 * @param length the length of the script; if negative, then the script need to be 177 * null terminated, 178 * @stable ICU 74 179 */ 180 U_CAPI void U_EXPORT2 181 ulocbld_setScript(ULocaleBuilder* builder, const char* script, int32_t length); 182 183 /** 184 * Sets the region. If region is the empty string, the region in this 185 * <code>ULocaleBuilder</code> is removed. Otherwise, the <code>region</code> 186 * must be well-formed, or else the ulocbld_buildLocaleID() and 187 * ulocbld_buildLanguageTag() methods will later report an 188 * U_ILLEGAL_ARGUMENT_ERROR. 189 * 190 * <p>The region value is defined by 191 * [unicode_region_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_region_subtag) 192 * as a two-letter ISO 3166 code or a three-digit UN M.49 area code. 193 * 194 * <p>The region value in the <code>Locale</code> created by the 195 * <code>ULocaleBuilder</code> is always normalized to upper case. 196 * 197 * @param builder the builder 198 * @param region the region, a const char * pointer (need not be terminated when 199 * the length is non-negative) 200 * @param length the length of the region; if negative, then the region need to be 201 * null terminated, 202 * @stable ICU 74 203 */ 204 U_CAPI void U_EXPORT2 205 ulocbld_setRegion(ULocaleBuilder* builder, const char* region, int32_t length); 206 207 /** 208 * Sets the variant. If variant is the empty string, the variant in this 209 * <code>ULocaleBuilder</code> is removed. Otherwise, the <code>variant</code> 210 * must be well-formed, or else the ulocbld_buildLocaleID() and 211 * ulocbld_buildLanguageTag() methods will later report an 212 * U_ILLEGAL_ARGUMENT_ERROR. 213 * 214 * <p><b>Note:</b> This method checks if <code>variant</code> 215 * satisfies the 216 * [unicode_variant_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_variant_subtag) 217 * syntax requirements, and normalizes the value to lowercase letters. However, 218 * the <code>Locale</code> class does not impose any syntactic 219 * restriction on variant. To set an ill-formed variant, use a Locale constructor. 220 * If there are multiple unicode_variant_subtag, the caller must concatenate 221 * them with '-' as separator (ex: "foobar-fibar"). 222 * 223 * @param builder the builder 224 * @param variant the variant, a const char * pointer (need not be terminated when 225 * the length is non-negative) 226 * @param length the length of the variant; if negative, then the variant need to be 227 * null terminated, 228 * @stable ICU 74 229 */ 230 U_CAPI void U_EXPORT2 231 ulocbld_setVariant(ULocaleBuilder* builder, const char* variant, int32_t length); 232 233 /** 234 * Sets the extension for the given key. If the value is the empty string, 235 * the extension is removed. Otherwise, the <code>key</code> and 236 * <code>value</code> must be well-formed, or else the ulocbld_buildLocaleID() 237 * and ulocbld_buildLanguageTag() methods will 238 * later report an U_ILLEGAL_ARGUMENT_ERROR. 239 * 240 * <p><b>Note:</b> The key ('u') is used for the Unicode locale extension. 241 * Setting a value for this key replaces any existing Unicode locale key/type 242 * pairs with those defined in the extension. 243 * 244 * <p><b>Note:</b> The key ('x') is used for the private use code. To be 245 * well-formed, the value for this key needs only to have subtags of one to 246 * eight alphanumeric characters, not two to eight as in the general case. 247 * 248 * @param builder the builder 249 * @param key the extension key 250 * @param value the value, a const char * pointer (need not be terminated when 251 * the length is non-negative) 252 * @param length the length of the value; if negative, then the value need to be 253 * null terminated, 254 * @stable ICU 74 255 */ 256 U_CAPI void U_EXPORT2 257 ulocbld_setExtension(ULocaleBuilder* builder, char key, const char* value, int32_t length); 258 259 /** 260 * Sets the Unicode locale keyword type for the given key. If the type 261 * StringPiece is constructed with a nullptr, the keyword is removed. 262 * If the type is the empty string, the keyword is set without type subtags. 263 * Otherwise, the key and type must be well-formed, or else the 264 * ulocbld_buildLocaleID() and ulocbld_buildLanguageTag() methods will later 265 * report an U_ILLEGAL_ARGUMENT_ERROR. 266 * 267 * <p>Keys and types are converted to lower case. 268 * 269 * <p><b>Note</b>:Setting the 'u' extension via {@link #ulocbld_setExtension} 270 * replaces all Unicode locale keywords with those defined in the 271 * extension. 272 * 273 * @param builder the builder 274 * @param key the Unicode locale key, a const char * pointer (need not be 275 * terminated when the length is non-negative) 276 * @param keyLength the length of the key; if negative, then the key need to be 277 * null terminated, 278 * @param type the Unicode locale type, a const char * pointer (need not be 279 * terminated when the length is non-negative) 280 * @param typeLength the length of the type; if negative, then the type need to 281 * be null terminated, 282 * @return This builder. 283 * @stable ICU 74 284 */ 285 U_CAPI void U_EXPORT2 286 ulocbld_setUnicodeLocaleKeyword(ULocaleBuilder* builder, 287 const char* key, int32_t keyLength, const char* type, int32_t typeLength); 288 289 /** 290 * Adds a unicode locale attribute, if not already present, otherwise 291 * has no effect. The attribute must not be empty string and must be 292 * well-formed or U_ILLEGAL_ARGUMENT_ERROR will be set to status 293 * during the ulocbld_buildLocaleID() and ulocbld_buildLanguageTag() calls. 294 * 295 * @param builder the builder 296 * @param attribute the attribute, a const char * pointer (need not be 297 * terminated when the length is non-negative) 298 * @param length the length of the attribute; if negative, then the attribute 299 * need to be null terminated, 300 * @stable ICU 74 301 */ 302 U_CAPI void U_EXPORT2 303 ulocbld_addUnicodeLocaleAttribute( 304 ULocaleBuilder* builder, const char* attribute, int32_t length); 305 306 /** 307 * Removes a unicode locale attribute, if present, otherwise has no 308 * effect. The attribute must not be empty string and must be well-formed 309 * or U_ILLEGAL_ARGUMENT_ERROR will be set to status during the ulocbld_buildLocaleID() 310 * and ulocbld_buildLanguageTag() calls. 311 * 312 * <p>Attribute comparison for removal is case-insensitive. 313 * 314 * @param builder the builder 315 * @param attribute the attribute, a const char * pointer (need not be 316 * terminated when the length is non-negative) 317 * @param length the length of the attribute; if negative, then the attribute 318 * need to be null terminated, 319 * @stable ICU 74 320 */ 321 U_CAPI void U_EXPORT2 322 ulocbld_removeUnicodeLocaleAttribute( 323 ULocaleBuilder* builder, const char* attribute, int32_t length); 324 325 /** 326 * Resets the builder to its initial, empty state. 327 * <p>This method clears the internal UErrorCode. 328 * 329 * @param builder the builder 330 * @stable ICU 74 331 */ 332 U_CAPI void U_EXPORT2 333 ulocbld_clear(ULocaleBuilder* builder); 334 335 /** 336 * Resets the extensions to their initial, empty state. 337 * Language, script, region and variant are unchanged. 338 * 339 * @param builder the builder 340 * @stable ICU 74 341 */ 342 U_CAPI void U_EXPORT2 343 ulocbld_clearExtensions(ULocaleBuilder* builder); 344 345 /** 346 * Build the LocaleID string from the fields set on this builder. 347 * If any set methods or during the ulocbld_buildLocaleID() call require memory 348 * allocation but fail U_MEMORY_ALLOCATION_ERROR will be set to status. 349 * If any of the fields set by the setters are not well-formed, the status 350 * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will 351 * not change after the ulocbld_buildLocaleID() call and the caller is 352 * free to keep using the same builder to build more locales. 353 * 354 * @param builder the builder 355 * @param locale the locale id 356 * @param localeCapacity the size of the locale buffer to store the locale id 357 * @param err the error code 358 * @return the length of the locale id in buffer 359 * @stable ICU 74 360 */ 361 U_CAPI int32_t U_EXPORT2 362 ulocbld_buildLocaleID(ULocaleBuilder* builder, char* locale, 363 int32_t localeCapacity, UErrorCode* err); 364 365 /** 366 * Build the ULocale object from the fields set on this builder. 367 * If any set methods or during the ulocbld_buildULocale() call require memory 368 * allocation but fail U_MEMORY_ALLOCATION_ERROR will be set to status. 369 * If any of the fields set by the setters are not well-formed, the status 370 * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will 371 * not change after the ulocbld_buildULocale() call and the caller is 372 * free to keep using the same builder to build more locales. 373 * 374 * @param builder the builder. 375 * @param err the error code. 376 * @return the locale, a ULocale* pointer. The created ULocale must be 377 * destroyed by calling {@link ulocale_close}. 378 * @stable ICU 74 379 */ 380 U_CAPI ULocale* U_EXPORT2 381 ulocbld_buildULocale(ULocaleBuilder* builder, UErrorCode* err); 382 383 /** 384 * Build the IETF BCP 47 language tag string from the fields set on this builder. 385 * If any set methods or during the ulocbld_buildLanguageTag() call require memory 386 * allocation but fail U_MEMORY_ALLOCATION_ERROR will be set to status. 387 * If any of the fields set by the setters are not well-formed, the status 388 * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will 389 * not change after the ulocbld_buildLanguageTag() call and the caller is free 390 * to keep using the same builder to build more locales. 391 * 392 * @param builder the builder 393 * @param language the language tag 394 * @param languageCapacity the size of the language buffer to store the language 395 * tag 396 * @param err the error code 397 * @return the length of the language tag in buffer 398 * @stable ICU 74 399 */ 400 U_CAPI int32_t U_EXPORT2 401 ulocbld_buildLanguageTag(ULocaleBuilder* builder, char* language, 402 int32_t languageCapacity, UErrorCode* err); 403 404 /** 405 * Sets the UErrorCode if an error occurred while recording sets. 406 * Preserves older error codes in the outErrorCode. 407 * 408 * @param builder the builder 409 * @param outErrorCode Set to an error code that occurred while setting subtags. 410 * Unchanged if there is no such error or if outErrorCode 411 * already contained an error. 412 * @return true if U_FAILURE(*outErrorCode) 413 * @stable ICU 74 414 */ 415 U_CAPI UBool U_EXPORT2 416 ulocbld_copyErrorTo(const ULocaleBuilder* builder, UErrorCode *outErrorCode); 417 418 #if U_SHOW_CPLUSPLUS_API 419 420 U_NAMESPACE_BEGIN 421 422 /** 423 * \class LocalULocaleBuilderPointer 424 * "Smart pointer" class, closes a ULocaleBuilder via ulocbld_close(). 425 * For most methods see the LocalPointerBase base class. 426 * 427 * @see LocalPointerBase 428 * @see LocalPointer 429 * @stable ICU 74 430 */ 431 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleBuilderPointer, ULocaleBuilder, ulocbld_close); 432 433 U_NAMESPACE_END 434 435 #endif /* U_SHOW_CPLUSPLUS_API */ 436 437 #endif // __ULOCBUILDER_H__