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/**
16 * \file
17 * \brief C++ API: Builder API for Locale
18 */
19
20U_NAMESPACE_BEGIN
21class 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 *
59 * @stable ICU 64
60 */
61class U_COMMON_API LocaleBuilder : public UObject {
62public:
63 /**
64 * Constructs an empty LocaleBuilder. The default value of all
65 * fields, extensions, and private use information is the
66 * empty string.
67 *
68 * @stable ICU 64
69 */
70 LocaleBuilder();
71
72 /**
73 * Destructor
74 * @stable ICU 64
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 *
88 * @stable ICU 64
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) .
95 * Discards the existing state. the empty string cause the builder to be
96 * reset, like {@link #clear}. Grandfathered tags are converted to their
97 * canonical form before being processed. Otherwise, the <code>language
98 * tag</code> must be well-formed, or else the build() method will later
99 * report an U_ILLEGAL_ARGUMENT_ERROR.
100 *
101 * <p>This method clears the internal UErrorCode.
102 *
103 * @param tag the language tag, defined as
104 * [unicode_locale_id](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id).
105 * @return This builder.
106 * @stable ICU 64
107 */
108 LocaleBuilder& setLanguageTag(StringPiece tag);
109
110 /**
111 * Sets the language. If <code>language</code> is the empty string, the
112 * language in this <code>LocaleBuilder</code> is removed. Otherwise, the
113 * <code>language</code> must be well-formed, or else the build() method will
114 * later report an U_ILLEGAL_ARGUMENT_ERROR.
115 *
116 * <p>The syntax of language value is defined as
117 * [unicode_language_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_language_subtag).
118 *
119 * @param language the language
120 * @return This builder.
121 * @stable ICU 64
122 */
123 LocaleBuilder& setLanguage(StringPiece language);
124
125 /**
126 * Sets the script. If <code>script</code> is the empty string, the script in
127 * this <code>LocaleBuilder</code> is removed.
128 * Otherwise, the <code>script</code> must be well-formed, or else the build()
129 * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
130 *
131 * <p>The script value is a four-letter script code as
132 * [unicode_script_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_script_subtag)
133 * defined by ISO 15924
134 *
135 * @param script the script
136 * @return This builder.
137 * @stable ICU 64
138 */
139 LocaleBuilder& setScript(StringPiece script);
140
141 /**
142 * Sets the region. If region is the empty string, the region in this
143 * <code>LocaleBuilder</code> is removed. Otherwise, the <code>region</code>
144 * must be well-formed, or else the build() method will later report an
145 * U_ILLEGAL_ARGUMENT_ERROR.
146 *
147 * <p>The region value is defined by
148 * [unicode_region_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_region_subtag)
149 * as a two-letter ISO 3166 code or a three-digit UN M.49 area code.
150 *
151 * <p>The region value in the <code>Locale</code> created by the
152 * <code>LocaleBuilder</code> is always normalized to upper case.
153 *
154 * @param region the region
155 * @return This builder.
156 * @stable ICU 64
157 */
158 LocaleBuilder& setRegion(StringPiece region);
159
160 /**
161 * Sets the variant. If variant is the empty string, the variant in this
162 * <code>LocaleBuilder</code> is removed. Otherwise, the <code>variant</code>
163 * must be well-formed, or else the build() method will later report an
164 * U_ILLEGAL_ARGUMENT_ERROR.
165 *
166 * <p><b>Note:</b> This method checks if <code>variant</code>
167 * satisfies the
168 * [unicode_variant_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_variant_subtag)
169 * syntax requirements, and normalizes the value to lowercase letters. However,
170 * the <code>Locale</code> class does not impose any syntactic
171 * restriction on variant. To set an ill-formed variant, use a Locale constructor.
172 * If there are multiple unicode_variant_subtag, the caller must concatenate
173 * them with '-' as separator (ex: "foobar-fibar").
174 *
175 * @param variant the variant
176 * @return This builder.
177 * @stable ICU 64
178 */
179 LocaleBuilder& setVariant(StringPiece variant);
180
181 /**
182 * Sets the extension for the given key. If the value is the empty string,
183 * the extension is removed. Otherwise, the <code>key</code> and
184 * <code>value</code> must be well-formed, or else the build() method will
185 * later report an U_ILLEGAL_ARGUMENT_ERROR.
186 *
187 * <p><b>Note:</b> The key ('u') is used for the Unicode locale extension.
188 * Setting a value for this key replaces any existing Unicode locale key/type
189 * pairs with those defined in the extension.
190 *
191 * <p><b>Note:</b> The key ('x') is used for the private use code. To be
192 * well-formed, the value for this key needs only to have subtags of one to
193 * eight alphanumeric characters, not two to eight as in the general case.
194 *
195 * @param key the extension key
196 * @param value the extension value
197 * @return This builder.
198 * @stable ICU 64
199 */
200 LocaleBuilder& setExtension(char key, StringPiece value);
201
202 /**
203 * Sets the Unicode locale keyword type for the given key. If the type
204 * StringPiece is constructed with a nullptr, the keyword is removed.
205 * If the type is the empty string, the keyword is set without type subtags.
206 * Otherwise, the key and type must be well-formed, or else the build()
207 * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
208 *
209 * <p>Keys and types are converted to lower case.
210 *
211 * <p><b>Note</b>:Setting the 'u' extension via {@link #setExtension}
212 * replaces all Unicode locale keywords with those defined in the
213 * extension.
214 *
215 * @param key the Unicode locale key
216 * @param type the Unicode locale type
217 * @return This builder.
218 * @stable ICU 64
219 */
220 LocaleBuilder& setUnicodeLocaleKeyword(
221 StringPiece key, StringPiece type);
222
223 /**
224 * Adds a unicode locale attribute, if not already present, otherwise
225 * has no effect. The attribute must not be empty string and must be
226 * well-formed or U_ILLEGAL_ARGUMENT_ERROR will be set to status
227 * during the build() call.
228 *
229 * @param attribute the attribute
230 * @return This builder.
231 * @stable ICU 64
232 */
233 LocaleBuilder& addUnicodeLocaleAttribute(StringPiece attribute);
234
235 /**
236 * Removes a unicode locale attribute, if present, otherwise has no
237 * effect. The attribute must not be empty string and must be well-formed
238 * or U_ILLEGAL_ARGUMENT_ERROR will be set to status during the build() call.
239 *
240 * <p>Attribute comparison for removal is case-insensitive.
241 *
242 * @param attribute the attribute
243 * @return This builder.
244 * @stable ICU 64
245 */
246 LocaleBuilder& removeUnicodeLocaleAttribute(StringPiece attribute);
247
248 /**
249 * Resets the builder to its initial, empty state.
250 * <p>This method clears the internal UErrorCode.
251 *
252 * @return this builder
253 * @stable ICU 64
254 */
255 LocaleBuilder& clear();
256
257 /**
258 * Resets the extensions to their initial, empty state.
259 * Language, script, region and variant are unchanged.
260 *
261 * @return this builder
262 * @stable ICU 64
263 */
264 LocaleBuilder& clearExtensions();
265
266 /**
267 * Returns an instance of <code>Locale</code> created from the fields set
268 * on this builder.
269 * If any set methods or during the build() call require memory allocation
270 * but fail U_MEMORY_ALLOCATION_ERROR will be set to status.
271 * If any of the fields set by the setters are not well-formed, the status
272 * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will
273 * not change after the build() call and the caller is free to keep using
274 * the same builder to build more locales.
275 *
276 * @return a new Locale
277 * @stable ICU 64
278 */
279 Locale build(UErrorCode& status);
280
281#ifndef U_HIDE_DRAFT_API
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.
288 * @return TRUE if U_FAILURE(outErrorCode)
289 * @draft ICU 65
290 */
291 UBool copyErrorTo(UErrorCode &outErrorCode) const;
292#endif /* U_HIDE_DRAFT_API */
293
294private:
295 friend class LocaleMatcher::Result;
296
297 void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode);
298
299 UErrorCode status_;
300 char language_[9];
301 char script_[5];
302 char region_[4];
303 CharString *variant_; // Pointer not object so we need not #include internal charstr.h.
304 icu::Locale *extensions_; // Pointer not object. Storage for all other fields.
305
306};
307
308U_NAMESPACE_END
309
310#endif /* U_SHOW_CPLUSPLUS_API */
311
312#endif // __LOCALEBUILDER_H__
313