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
21U_NAMESPACE_BEGIN
22class 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 */
62class U_COMMON_API LocaleBuilder : public UObject {
63public:
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
295private:
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
309U_NAMESPACE_END
310
311#endif // U_HIDE_DRAFT_API
312
313#endif /* U_SHOW_CPLUSPLUS_API */
314
315#endif // __LOCALEBUILDER_H__
316