ICU 75.1 75.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
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 <optional>
15
16 #include "unicode/locid.h"
17 #include "unicode/stringpiece.h"
18 #include "unicode/uobject.h"
19
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
113 enum ULocMatchDirection {
119 ULOCMATCH_DIRECTION_WITH_ONE_WAY,
126 ULOCMATCH_DIRECTION_ONLY_TWO_WAY
127 };
128 #ifndef U_IN_DOXYGEN
129 typedef enum ULocMatchDirection ULocMatchDirection;
130 #endif
131
132 struct UHashtable;
133
134 U_NAMESPACE_BEGIN
135
136 struct LSR;
137
138 class LikelySubtags;
139 class LocaleDistance;
140 class LocaleLsrIterator;
141 class UVector;
142
186 class U_COMMON_API LocaleMatcher : public UMemory {
187 public:
194 class U_COMMON_API Result : public UMemory {
195 public:
203 Result(Result &&src) noexcept;
204
210 ~Result();
211
219 Result &operator=(Result &&src) noexcept;
220
228 inline const Locale *getDesiredLocale() const { return desiredLocale; }
229
239 inline const Locale *getSupportedLocale() const { return supportedLocale; }
240
248 inline int32_t getDesiredIndex() const { return desiredIndex; }
249
260 inline int32_t getSupportedIndex() const { return supportedIndex; }
261
274 Locale makeResolvedLocale(UErrorCode &errorCode) const;
275
276 private:
277 Result(const Locale *desired, const Locale *supported,
278 int32_t desIndex, int32_t suppIndex, UBool owned) :
279 desiredLocale(desired), supportedLocale(supported),
280 desiredIndex(desIndex), supportedIndex(suppIndex),
281 desiredIsOwned(owned) {}
282
283 Result(const Result &other) = delete;
284 Result &operator=(const Result &other) = delete;
285
286 const Locale *desiredLocale;
287 const Locale *supportedLocale;
288 int32_t desiredIndex;
289 int32_t supportedIndex;
290 UBool desiredIsOwned;
291
292 friend class LocaleMatcher;
293 };
294
301 class U_COMMON_API Builder : public UMemory {
302 public:
309 Builder() {}
310
318 Builder(Builder &&src) noexcept;
319
325 ~Builder();
326
334 Builder &operator=(Builder &&src) noexcept;
335
347 Builder &setSupportedLocalesFromListString(StringPiece locales);
348
358 Builder &setSupportedLocales(Locale::Iterator &locales);
359
373 template<typename Iter>
374 Builder &setSupportedLocales(Iter begin, Iter end) {
375 if (U_FAILURE(errorCode_)) { return *this; }
376 clearSupportedLocales();
377 while (begin != end) {
378 addSupportedLocale(*begin++);
379 }
380 return *this;
381 }
382
398 template<typename Iter, typename Conv>
399 Builder &setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter) {
400 if (U_FAILURE(errorCode_)) { return *this; }
401 clearSupportedLocales();
402 while (begin != end) {
403 addSupportedLocale(converter(*begin++));
404 }
405 return *this;
406 }
407
416 Builder &addSupportedLocale(const Locale &locale);
417
426 Builder &setNoDefaultLocale();
427
438 Builder &setDefaultLocale(const Locale *defaultLocale);
439
450 Builder &setFavorSubtag(ULocMatchFavorSubtag subtag);
451
460 Builder &setDemotionPerDesiredLocale(ULocMatchDemotion demotion);
461
470 Builder &setDirection(ULocMatchDirection matchDirection) {
471 if (U_SUCCESS(errorCode_)) {
472 direction_ = matchDirection;
473 }
474 return *this;
475 }
476
498 Builder &setMaxDistance(const Locale &desired, const Locale &supported);
499
510 UBool copyErrorTo(UErrorCode &outErrorCode) const;
511
522 LocaleMatcher build(UErrorCode &errorCode) const;
523
524 private:
525 friend class LocaleMatcher;
526
527 Builder(const Builder &other) = delete;
528 Builder &operator=(const Builder &other) = delete;
529
530 void clearSupportedLocales();
531 bool ensureSupportedLocaleVector();
532
533 UErrorCode errorCode_ = U_ZERO_ERROR;
534 UVector *supportedLocales_ = nullptr;
535 int32_t thresholdDistance_ = -1;
536 ULocMatchDemotion demotion_ = ULOCMATCH_DEMOTION_REGION;
537 Locale *defaultLocale_ = nullptr;
538 bool withDefault_ = true;
539 ULocMatchFavorSubtag favor_ = ULOCMATCH_FAVOR_LANGUAGE;
540 ULocMatchDirection direction_ = ULOCMATCH_DIRECTION_WITH_ONE_WAY;
541 Locale *maxDistanceDesired_ = nullptr;
542 Locale *maxDistanceSupported_ = nullptr;
543 };
544
545 // FYI No public LocaleMatcher constructors in C++; use the Builder.
546
553 LocaleMatcher(LocaleMatcher &&src) noexcept;
554
559 ~LocaleMatcher();
560
569 LocaleMatcher &operator=(LocaleMatcher &&src) noexcept;
570
581 const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const;
582
593 const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
594
609 const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const;
610
623 Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const;
624
637 Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
638
652 UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
653
654 #ifndef U_HIDE_INTERNAL_API
673 double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
674 #endif // U_HIDE_INTERNAL_API
675
676 private:
677 LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
678 LocaleMatcher(const LocaleMatcher &other) = delete;
679 LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
680
681 int32_t putIfAbsent(const LSR &lsr, int32_t i, int32_t suppLength, UErrorCode &errorCode);
682
683 std::optional<int32_t> getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
684
685 const LikelySubtags &likelySubtags;
686 const LocaleDistance &localeDistance;
687 int32_t thresholdDistance;
688 int32_t demotionPerDesiredLocale;
689 ULocMatchFavorSubtag favorSubtag;
690 ULocMatchDirection direction;
691
692 // These are in input order.
693 const Locale ** supportedLocales;
694 LSR *lsrs;
695 int32_t supportedLocalesLength;
696 // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
697 UHashtable *supportedLsrToIndex; // Map<LSR, Integer>
698 // Array versions of the supportedLsrToIndex keys and values.
699 // The distance lookup loops over the supportedLSRs and returns the index of the best match.
700 const LSR **supportedLSRs;
701 int32_t *supportedIndexes;
702 int32_t supportedLSRsLength;
703 Locale *ownedDefaultLocale;
704 const Locale *defaultLocale;
705 };
706
707 U_NAMESPACE_END
708
709 #endif // U_SHOW_CPLUSPLUS_API
710 #endif // __LOCALEMATCHER_H__
icu::LocaleMatcher::Builder
LocaleMatcher builder.
Definition: localematcher.h:301
icu::LocaleMatcher::Builder::setFavorSubtag
Builder & setFavorSubtag(ULocMatchFavorSubtag subtag)
If ULOCMATCH_FAVOR_SCRIPT, then the language differences are smaller than script differences.
icu::LocaleMatcher::Builder::addSupportedLocale
Builder & addSupportedLocale(const Locale &locale)
Adds another supported locale.
icu::LocaleMatcher::Builder::Builder
Builder(Builder &&src) noexcept
Move constructor; might modify the source.
icu::LocaleMatcher::Builder::setSupportedLocales
Builder & setSupportedLocales(Locale::Iterator &locales)
Copies the supported locales, preserving iteration order.
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:374
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:399
icu::LocaleMatcher::Builder::~Builder
~Builder()
Destructor.
icu::LocaleMatcher::Builder::build
LocaleMatcher build(UErrorCode &errorCode) const
Builds and returns a new locale matcher.
icu::LocaleMatcher::Builder::setSupportedLocalesFromListString
Builder & setSupportedLocalesFromListString(StringPiece locales)
Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0....
icu::LocaleMatcher::Builder::setDirection
Builder & setDirection(ULocMatchDirection matchDirection)
Option for whether to include or ignore one-way (fallback) match data.
Definition: localematcher.h:470
icu::LocaleMatcher::Builder::setMaxDistance
Builder & setMaxDistance(const Locale &desired, const Locale &supported)
Sets the maximum distance for an acceptable match.
icu::LocaleMatcher::Builder::setNoDefaultLocale
Builder & setNoDefaultLocale()
Sets no default locale.
icu::LocaleMatcher::Builder::setDefaultLocale
Builder & setDefaultLocale(const Locale *defaultLocale)
Sets the default locale; if nullptr, or if it is not set explicitly, then the first supported locale ...
icu::LocaleMatcher::Builder::setDemotionPerDesiredLocale
Builder & setDemotionPerDesiredLocale(ULocMatchDemotion demotion)
Option for whether all desired locales are treated equally or earlier ones are preferred (this is the...
icu::LocaleMatcher::Builder::operator=
Builder & operator=(Builder &&src) noexcept
Move assignment; might modify the source.
icu::LocaleMatcher::Builder::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred while setting parameters.
icu::LocaleMatcher::Builder::Builder
Builder()
Constructs a builder used in chaining parameters for building a LocaleMatcher.
Definition: localematcher.h:309
icu::LocaleMatcher::Result
Data for the best-matching pair of a desired and a supported locale.
Definition: localematcher.h:194
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 order...
Definition: localematcher.h:260
icu::LocaleMatcher::Result::getSupportedLocale
const Locale * getSupportedLocale() const
Returns the best-matching supported locale.
Definition: localematcher.h:239
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:248
icu::LocaleMatcher::Result::makeResolvedLocale
Locale makeResolvedLocale(UErrorCode &errorCode) const
Takes the best-matching supported locale and adds relevant fields of the best-matching desired locale...
icu::LocaleMatcher::Result::~Result
~Result()
Destructor.
icu::LocaleMatcher::Result::operator=
Result & operator=(Result &&src) noexcept
Move assignment; might modify the source.
icu::LocaleMatcher::Result::getDesiredLocale
const Locale * getDesiredLocale() const
Returns the best-matching desired locale.
Definition: localematcher.h:228
icu::LocaleMatcher::Result::Result
Result(Result &&src) noexcept
Move constructor; might modify the source.
icu::LocaleMatcher
Immutable class that picks the best match between a user's desired locales and an application's suppo...
Definition: localematcher.h:186
icu::LocaleMatcher::getBestMatch
const Locale * getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const
Returns the supported locale which best matches the desired locale.
icu::LocaleMatcher::LocaleMatcher
LocaleMatcher(LocaleMatcher &&src) noexcept
Move copy constructor; might modify the source.
icu::LocaleMatcher::isMatch
UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const
Returns true if the pair of locales matches acceptably.
icu::LocaleMatcher::getBestMatchResult
Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const
Returns the best match between the desired locale and the supported locales.
icu::LocaleMatcher::getBestMatchResult
Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const
Returns the best match between the desired and supported locales.
icu::LocaleMatcher::internalMatch
double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const
Returns a fraction between 0 and 1, where 1 means that the languages are a perfect match,...
icu::LocaleMatcher::getBestMatchForListString
const Locale * getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const
Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0....
icu::LocaleMatcher::~LocaleMatcher
~LocaleMatcher()
Destructor.
icu::LocaleMatcher::getBestMatch
const Locale * getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const
Returns the supported locale which best matches one of the desired locales.
icu::LocaleMatcher::operator=
LocaleMatcher & operator=(LocaleMatcher &&src) noexcept
Move assignment operator; might modify the source.
icu::Locale::Iterator
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1016
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
icu::StringPiece
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:115
ULocMatchDemotion
ULocMatchDemotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred.
Definition: localematcher.h:57
ULOCMATCH_DEMOTION_REGION
@ ULOCMATCH_DEMOTION_REGION
Earlier desired locales are preferred.
Definition: localematcher.h:90
ULOCMATCH_DEMOTION_NONE
@ ULOCMATCH_DEMOTION_NONE
All desired locales are treated equally.
Definition: localematcher.h:63
ULocMatchDirection
ULocMatchDirection
Builder option for whether to include or ignore one-way (fallback) match data.
Definition: localematcher.h:113
ULOCMATCH_DIRECTION_ONLY_TWO_WAY
@ ULOCMATCH_DIRECTION_ONLY_TWO_WAY
Locale matching limited to two-way matches including e.g.
Definition: localematcher.h:126
ULOCMATCH_DIRECTION_WITH_ONE_WAY
@ ULOCMATCH_DIRECTION_WITH_ONE_WAY
Locale matching includes one-way matches such as Breton→French.
Definition: localematcher.h:119
ULocMatchFavorSubtag
ULocMatchFavorSubtag
Builder option for whether the language subtag or the script subtag is most important.
Definition: localematcher.h:31
ULOCMATCH_FAVOR_SCRIPT
@ ULOCMATCH_FAVOR_SCRIPT
Makes script differences matter relatively more than language differences.
Definition: localematcher.h:44
ULOCMATCH_FAVOR_LANGUAGE
@ ULOCMATCH_FAVOR_LANGUAGE
Language differences are most important, then script differences, then region differences.
Definition: localematcher.h:38
locid.h
C++ API: Locale ID object.
UHashtable
struct UHashtable UHashtable
Definition: msgfmt.h:43
stringpiece.h
C++ API: StringPiece: Read-only byte string wrapper class.
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
uobject.h
C++ API: Common ICU base class UObject.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
U_ZERO_ERROR
@ U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:450
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:733
U_SUCCESS
#define U_SUCCESS(x)
Does the error code indicate success?
Definition: utypes.h:728
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