[apple/icu.git] / icuSources / common / unicode / localebuilder.h

// © 2018 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html#License
#ifndef __LOCALEBUILDER_H__
#define __LOCALEBUILDER_H__

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

#include "unicode/locid.h"
#include "unicode/localematcher.h"
#include "unicode/stringpiece.h"
#include "unicode/uobject.h"

#ifndef U_HIDE_DRAFT_API
/**
 * \file
 * \brief C++ API: Builder API for Locale
 */

U_NAMESPACE_BEGIN
class CharString;

/**
 * <code>LocaleBuilder</code> is used to build instances of <code>Locale</code>
 * from values configured by the setters.  Unlike the <code>Locale</code>
 * constructors, the <code>LocaleBuilder</code> checks if a value configured by a
 * setter satisfies the syntax requirements defined by the <code>Locale</code>
 * class.  A <code>Locale</code> object created by a <code>LocaleBuilder</code> is
 * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
 * without losing information.
 *
 * <p>The following example shows how to create a <code>Locale</code> object
 * with the <code>LocaleBuilder</code>.
 * <blockquote>
 * <pre>
 *     UErrorCode status = U_ZERO_ERROR;
 *     Locale aLocale = LocaleBuilder()
 *                          .setLanguage("sr")
 *                          .setScript("Latn")
 *                          .setRegion("RS")
 *                          .build(status);
 *     if (U_SUCCESS(status)) {
 *       // ...
 *     }
 * </pre>
 * </blockquote>
 *
 * <p>LocaleBuilders can be reused; <code>clear()</code> resets all
 * fields to their default values.
 *
 * <p>LocaleBuilder tracks errors in an internal UErrorCode. For all setters,
 * except setLanguageTag and setLocale, LocaleBuilder will return immediately
 * if the internal UErrorCode is in error state.
 * To reset internal state and error code, call clear method.
 * The setLanguageTag and setLocale method will first clear the internal
 * UErrorCode, then track the error of the validation of the input parameter
 * into the internal UErrorCode.
 *
 * @draft ICU 64
 */
class U_COMMON_API LocaleBuilder : public UObject {
public:
    /**
     * Constructs an empty LocaleBuilder. The default value of all
     * fields, extensions, and private use information is the
     * empty string.
     *
     * @draft ICU 64
     */
    LocaleBuilder();

    /**
     * Destructor
     * @draft ICU 64
     */
    virtual ~LocaleBuilder();

    /**
     * Resets the <code>LocaleBuilder</code> to match the provided
     * <code>locale</code>.  Existing state is discarded.
     *
     * <p>All fields of the locale must be well-formed.
     * <p>This method clears the internal UErrorCode.
     *
     * @param locale the locale
     * @return This builder.
     *
     * @draft ICU 64
     */
    LocaleBuilder& setLocale(const Locale& locale);

    /**
     * Resets the LocaleBuilder to match the provided
     * [Unicode Locale Identifier](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id) .
     * Discards the existing state. the empty string cause the builder to be
     * reset, like {@link #clear}.  Grandfathered tags are converted to their
     * canonical form before being processed.  Otherwise, the <code>language
     * tag</code> must be well-formed, or else the build() method will later
     * report an U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p>This method clears the internal UErrorCode.
     *
     * @param tag the language tag, defined as
     *   [unicode_locale_id](http://www.unicode.org/reports/tr35/tr35.html#unicode_locale_id).
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setLanguageTag(StringPiece tag);

    /**
     * Sets the language.  If <code>language</code> is the empty string, the
     * language in this <code>LocaleBuilder</code> is removed. Otherwise, the
     * <code>language</code> must be well-formed, or else the build() method will
     * later report an U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p>The syntax of language value is defined as
     * [unicode_language_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_language_subtag).
     *
     * @param language the language
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setLanguage(StringPiece language);

    /**
     * Sets the script. If <code>script</code> is the empty string, the script in
     * this <code>LocaleBuilder</code> is removed.
     * Otherwise, the <code>script</code> must be well-formed, or else the build()
     * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p>The script value is a four-letter script code as
     * [unicode_script_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_script_subtag)
     * defined by ISO 15924
     *
     * @param script the script
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setScript(StringPiece script);

    /**
     * Sets the region.  If region is the empty string, the region in this
     * <code>LocaleBuilder</code> is removed. Otherwise, the <code>region</code>
     * must be well-formed, or else the build() method will later report an
     * U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p>The region value is defined by
     *  [unicode_region_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_region_subtag)
     * as a two-letter ISO 3166 code or a three-digit UN M.49 area code.
     *
     * <p>The region value in the <code>Locale</code> created by the
     * <code>LocaleBuilder</code> is always normalized to upper case.
     *
     * @param region the region
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setRegion(StringPiece region);

    /**
     * Sets the variant.  If variant is the empty string, the variant in this
     * <code>LocaleBuilder</code> is removed.  Otherwise, the <code>variant</code>
     * must be well-formed, or else the build() method will later report an
     * U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p><b>Note:</b> This method checks if <code>variant</code>
     * satisfies the
     * [unicode_variant_subtag](http://www.unicode.org/reports/tr35/tr35.html#unicode_variant_subtag)
     * syntax requirements, and normalizes the value to lowercase letters. However,
     * the <code>Locale</code> class does not impose any syntactic
     * restriction on variant. To set an ill-formed variant, use a Locale constructor.
     * If there are multiple unicode_variant_subtag, the caller must concatenate
     * them with '-' as separator (ex: "foobar-fibar").
     *
     * @param variant the variant
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setVariant(StringPiece variant);

    /**
     * Sets the extension for the given key. If the value is the empty string,
     * the extension is removed.  Otherwise, the <code>key</code> and
     * <code>value</code> must be well-formed, or else the build() method will
     * later report an U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p><b>Note:</b> The key ('u') is used for the Unicode locale extension.
     * Setting a value for this key replaces any existing Unicode locale key/type
     * pairs with those defined in the extension.
     *
     * <p><b>Note:</b> The key ('x') is used for the private use code. To be
     * well-formed, the value for this key needs only to have subtags of one to
     * eight alphanumeric characters, not two to eight as in the general case.
     *
     * @param key the extension key
     * @param value the extension value
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setExtension(char key, StringPiece value);

    /**
     * Sets the Unicode locale keyword type for the given key. If the type
     * StringPiece is constructed with a nullptr, the keyword is removed.
     * If the type is the empty string, the keyword is set without type subtags.
     * Otherwise, the key and type must be well-formed, or else the build()
     * method will later report an U_ILLEGAL_ARGUMENT_ERROR.
     *
     * <p>Keys and types are converted to lower case.
     *
     * <p><b>Note</b>:Setting the 'u' extension via {@link #setExtension}
     * replaces all Unicode locale keywords with those defined in the
     * extension.
     *
     * @param key the Unicode locale key
     * @param type the Unicode locale type
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& setUnicodeLocaleKeyword(
        StringPiece key, StringPiece type);

    /**
     * Adds a unicode locale attribute, if not already present, otherwise
     * has no effect.  The attribute must not be empty string and must be
     * well-formed or U_ILLEGAL_ARGUMENT_ERROR will be set to status
     * during the build() call.
     *
     * @param attribute the attribute
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& addUnicodeLocaleAttribute(StringPiece attribute);

    /**
     * Removes a unicode locale attribute, if present, otherwise has no
     * effect.  The attribute must not be empty string and must be well-formed
     * or U_ILLEGAL_ARGUMENT_ERROR will be set to status during the build() call.
     *
     * <p>Attribute comparison for removal is case-insensitive.
     *
     * @param attribute the attribute
     * @return This builder.
     * @draft ICU 64
     */
    LocaleBuilder& removeUnicodeLocaleAttribute(StringPiece attribute);

    /**
     * Resets the builder to its initial, empty state.
     * <p>This method clears the internal UErrorCode.
     *
     * @return this builder
     * @draft ICU 64
     */
    LocaleBuilder& clear();

    /**
     * Resets the extensions to their initial, empty state.
     * Language, script, region and variant are unchanged.
     *
     * @return this builder
     * @draft ICU 64
     */
    LocaleBuilder& clearExtensions();

    /**
     * Returns an instance of <code>Locale</code> created from the fields set
     * on this builder.
     * If any set methods or during the build() call require memory allocation
     * but fail U_MEMORY_ALLOCATION_ERROR will be set to status.
     * If any of the fields set by the setters are not well-formed, the status
     * will be set to U_ILLEGAL_ARGUMENT_ERROR. The state of the builder will
     * not change after the build() call and the caller is free to keep using
     * the same builder to build more locales.
     *
     * @return a new Locale
     * @draft ICU 64
     */
    Locale build(UErrorCode& status);

#ifndef U_HIDE_DRAFT_API
    /**
     * Sets the UErrorCode if an error occurred while recording sets.
     * Preserves older error codes in the outErrorCode.
     * @param outErrorCode Set to an error code that occurred while setting subtags.
     *                  Unchanged if there is no such error or if outErrorCode
     *                  already contained an error.
     * @return TRUE if U_FAILURE(outErrorCode)
     * @draft ICU 65
     */
    UBool copyErrorTo(UErrorCode &outErrorCode) const;
#endif  /* U_HIDE_DRAFT_API */

private:
    friend class LocaleMatcher::Result;

    void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode);

    UErrorCode status_;
    char language_[9];
    char script_[5];
    char region_[4];
    CharString *variant_;  // Pointer not object so we need not #include internal charstr.h.
    icu::Locale *extensions_;  // Pointer not object. Storage for all other fields.

};

U_NAMESPACE_END

#endif  // U_HIDE_DRAFT_API

#endif /* U_SHOW_CPLUSPLUS_API */

#endif  // __LOCALEBUILDER_H__
Commit	Line	Data
3d1f044b A	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
340931cb A	6	#include "unicode/utypes.h"
	7
	8	#if U_SHOW_CPLUSPLUS_API
	9
3d1f044b	10	#include "unicode/locid.h"
340931cb	11	#include "unicode/localematcher.h"
3d1f044b A	12	#include "unicode/stringpiece.h"
3d1f044b A	13	#include "unicode/uobject.h"
3d1f044b A	14
	15	#ifndef U_HIDE_DRAFT_API
	16	/**
	17	* \file
	18	* \brief C++ API: Builder API for Locale
	19	*/
	20
3d1f044b A	21	U_NAMESPACE_BEGIN
	22	class 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	*/
	62	class U_COMMON_API LocaleBuilder : public UObject {
	63	public:
	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
340931cb A	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
3d1f044b	295	private:
340931cb A	296	friend class LocaleMatcher::Result;
	297
	298	void copyExtensionsFrom(const Locale& src, UErrorCode& errorCode);
	299
3d1f044b A	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
	309	U_NAMESPACE_END
3d1f044b A	310
3d1f044b A	311	#endif // U_HIDE_DRAFT_API
340931cb A	312
	313	#endif /* U_SHOW_CPLUSPLUS_API */
	314
3d1f044b	315	#endif // __LOCALEBUILDER_H__