ICU 65.1 65.1

localematcher.h
Go to the documentation of this file.
1 // © 2019 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html#License
3
4 // localematcher.h
5 // created: 2019may08 Markus W. Scherer
6
7 #ifndef __LOCALEMATCHER_H__
8 #define __LOCALEMATCHER_H__
9
10 #include "unicode/utypes.h"
11
12 #if U_SHOW_CPLUSPLUS_API
13
14 #include "unicode/locid.h"
15 #include "unicode/stringpiece.h"
16 #include "unicode/uobject.h"
17
23 #ifndef U_HIDE_DRAFT_API
24
31 enum ULocMatchFavorSubtag {
38 ULOCMATCH_FAVOR_LANGUAGE,
44 ULOCMATCH_FAVOR_SCRIPT
45 };
46 #ifndef U_IN_DOXYGEN
47 typedef enum ULocMatchFavorSubtag ULocMatchFavorSubtag;
48 #endif
49
57 enum ULocMatchDemotion {
63 ULOCMATCH_DEMOTION_NONE,
90 ULOCMATCH_DEMOTION_REGION
91 };
92 #ifndef U_IN_DOXYGEN
93 typedef enum ULocMatchDemotion ULocMatchDemotion;
94 #endif
95
96 struct UHashtable;
97
98 U_NAMESPACE_BEGIN
99
100 struct LSR;
101
102 class LocaleDistance;
103 class LocaleLsrIterator;
104 class UVector;
105 class XLikelySubtags;
106
150 class U_COMMON_API LocaleMatcher : public UMemory {
151 public:
158 class U_COMMON_API Result : public UMemory {
159 public:
167 Result(Result &&src) U_NOEXCEPT;
168
174 ~Result();
175
183 Result &operator=(Result &&src) U_NOEXCEPT;
184
192 inline const Locale *getDesiredLocale() const { return desiredLocale; }
193
203 inline const Locale *getSupportedLocale() const { return supportedLocale; }
204
212 inline int32_t getDesiredIndex() const { return desiredIndex; }
213
224 inline int32_t getSupportedIndex() const { return supportedIndex; }
225
238 Locale makeResolvedLocale(UErrorCode &errorCode) const;
239
240 private:
241 Result(const Locale *desired, const Locale *supported,
242 int32_t desIndex, int32_t suppIndex, UBool owned) :
243 desiredLocale(desired), supportedLocale(supported),
244 desiredIndex(desIndex), supportedIndex(suppIndex),
245 desiredIsOwned(owned) {}
246
247 Result(const Result &other) = delete;
248 Result &operator=(const Result &other) = delete;
249
250 const Locale *desiredLocale;
251 const Locale *supportedLocale;
252 int32_t desiredIndex;
253 int32_t supportedIndex;
254 UBool desiredIsOwned;
255
256 friend class LocaleMatcher;
257 };
258
266 class U_COMMON_API Builder : public UMemory {
267 public:
274 Builder() {}
275
283 Builder(Builder &&src) U_NOEXCEPT;
284
290 ~Builder();
291
299 Builder &operator=(Builder &&src) U_NOEXCEPT;
300
312 Builder &setSupportedLocalesFromListString(StringPiece locales);
313
323 Builder &setSupportedLocales(Locale::Iterator &locales);
324
338 template<typename Iter>
339 Builder &setSupportedLocales(Iter begin, Iter end) {
340 if (U_FAILURE(errorCode_)) { return *this; }
341 clearSupportedLocales();
342 while (begin != end) {
343 addSupportedLocale(*begin++);
344 }
345 return *this;
346 }
347
363 template<typename Iter, typename Conv>
364 Builder &setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter) {
365 if (U_FAILURE(errorCode_)) { return *this; }
366 clearSupportedLocales();
367 while (begin != end) {
368 addSupportedLocale(converter(*begin++));
369 }
370 return *this;
371 }
372
381 Builder &addSupportedLocale(const Locale &locale);
382
391 Builder &setDefaultLocale(const Locale *defaultLocale);
392
403 Builder &setFavorSubtag(ULocMatchFavorSubtag subtag);
404
413 Builder &setDemotionPerDesiredLocale(ULocMatchDemotion demotion);
414
425 UBool copyErrorTo(UErrorCode &outErrorCode) const;
426
437 LocaleMatcher build(UErrorCode &errorCode) const;
438
439 private:
440 friend class LocaleMatcher;
441
442 Builder(const Builder &other) = delete;
443 Builder &operator=(const Builder &other) = delete;
444
445 void clearSupportedLocales();
446 bool ensureSupportedLocaleVector();
447
448 UErrorCode errorCode_ = U_ZERO_ERROR;
449 UVector *supportedLocales_ = nullptr;
450 int32_t thresholdDistance_ = -1;
451 ULocMatchDemotion demotion_ = ULOCMATCH_DEMOTION_REGION;
452 Locale *defaultLocale_ = nullptr;
453 ULocMatchFavorSubtag favor_ = ULOCMATCH_FAVOR_LANGUAGE;
454 };
455
456 // FYI No public LocaleMatcher constructors in C++; use the Builder.
457
464 LocaleMatcher(LocaleMatcher &&src) U_NOEXCEPT;
465
470 ~LocaleMatcher();
471
480 LocaleMatcher &operator=(LocaleMatcher &&src) U_NOEXCEPT;
481
492 const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const;
493
504 const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
505
520 const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const;
521
534 Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const;
535
548 Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
549
550 #ifndef U_HIDE_INTERNAL_API
551
569 double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
570 #endif // U_HIDE_INTERNAL_API
571
572 private:
573 LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
574 LocaleMatcher(const LocaleMatcher &other) = delete;
575 LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
576
577 int32_t getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
578
579 const XLikelySubtags &likelySubtags;
580 const LocaleDistance &localeDistance;
581 int32_t thresholdDistance;
582 int32_t demotionPerDesiredLocale;
583 ULocMatchFavorSubtag favorSubtag;
584
585 // These are in input order.
586 const Locale ** supportedLocales;
587 LSR *lsrs;
588 int32_t supportedLocalesLength;
589 // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
590 UHashtable *supportedLsrToIndex; // Map<LSR, Integer> stores index+1 because 0 is "not found"
591 // Array versions of the supportedLsrToIndex keys and values.
592 // The distance lookup loops over the supportedLSRs and returns the index of the best match.
593 const LSR **supportedLSRs;
594 int32_t *supportedIndexes;
595 int32_t supportedLSRsLength;
596 Locale *ownedDefaultLocale;
597 const Locale *defaultLocale;
598 int32_t defaultLocaleIndex;
599 };
600
601 U_NAMESPACE_END
602
603 #endif // U_HIDE_DRAFT_API
604 #endif // U_SHOW_CPLUSPLUS_API
605 #endif // __LOCALEMATCHER_H__
icu::LocaleMatcher::Result::getSupportedIndex
int32_t getSupportedIndex() const
Returns the index of the best-matching supported locale in the constructor’s or builder’s input ord...
Definition: localematcher.h:224
UHashtable
struct UHashtable UHashtable
Definition: msgfmt.h:43
ULOCMATCH_DEMOTION_NONE
All desired locales are treated equally.
Definition: localematcher.h:63
icu::LocaleMatcher::Builder::setSupportedLocalesViaConverter
Builder & setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter)
Copies the supported locales from the begin/end range, preserving iteration order.
Definition: localematcher.h:364
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:709
ULocMatchDemotion
ULocMatchDemotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred...
Definition: localematcher.h:57
ULOCMATCH_FAVOR_SCRIPT
Makes script differences matter relatively more than language differences.
Definition: localematcher.h:44
icu::LocaleMatcher::Builder::setSupportedLocales
Builder & setSupportedLocales(Iter begin, Iter end)
Copies the supported locales from the begin/end range, preserving iteration order.
Definition: localematcher.h:339
icu::LocaleMatcher::Result::getDesiredLocale
const Locale * getDesiredLocale() const
Returns the best-matching desired locale.
Definition: localematcher.h:192
U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449
ULOCMATCH_DEMOTION_REGION
Earlier desired locales are preferred.
Definition: localematcher.h:90
icu::Locale::Iterator
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1003
stringpiece.h
C++ API: StringPiece: Read-only byte string wrapper class.
ULocMatchFavorSubtag
ULocMatchFavorSubtag
Builder option for whether the language subtag or the script subtag is most important.
Definition: localematcher.h:31
icu::LocaleMatcher
Immutable class that picks the best match between a user&#39;s desired locales and an application&#39;s suppo...
Definition: localematcher.h:150
icu::LocaleMatcher::Builder::Builder
Builder()
Constructs a builder used in chaining parameters for building a LocaleMatcher.
Definition: localematcher.h:274
icu::LocaleMatcher::Result::getDesiredIndex
int32_t getDesiredIndex() const
Returns the index of the best-matching desired locale in the input Iterable order.
Definition: localematcher.h:212
icu::LocaleMatcher::Result::getSupportedLocale
const Locale * getSupportedLocale() const
Returns the best-matching supported locale.
Definition: localematcher.h:203
icu::LocaleMatcher::Result
Data for the best-matching pair of a desired and a supported locale.
Definition: localematcher.h:158
uobject.h
C++ API: Common ICU base class UObject.
U_NOEXCEPT
#define U_NOEXCEPT
"noexcept" if supported, otherwise empty.
Definition: platform.h:529
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
locid.h
C++ API: Locale ID object.
ULOCMATCH_FAVOR_LANGUAGE
Language differences are most important, then script differences, then region differences.
Definition: localematcher.h:38
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
U_COMMON_API
#define U_COMMON_API
Set to export library symbols from inside the common library, and to import them from outside...
Definition: utypes.h:300
icu::StringPiece
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
icu::LocaleMatcher::Builder
LocaleMatcher builder.
Definition: localematcher.h:266
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:115
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:261
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195