icuSources/common/unicode/localebuilder.h

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