Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/localebuilder.h @ 69:33d812a61356

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