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