ICU 69.1 69.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 "unicode/locid.h"
15 #include "unicode/stringpiece.h"
16 #include "unicode/uobject.h"
17
29 enum ULocMatchFavorSubtag {
36 ULOCMATCH_FAVOR_LANGUAGE,
42 ULOCMATCH_FAVOR_SCRIPT
43 };
44 #ifndef U_IN_DOXYGEN
45 typedef enum ULocMatchFavorSubtag ULocMatchFavorSubtag;
46 #endif
47
55 enum ULocMatchDemotion {
61 ULOCMATCH_DEMOTION_NONE,
88 ULOCMATCH_DEMOTION_REGION
89 };
90 #ifndef U_IN_DOXYGEN
91 typedef enum ULocMatchDemotion ULocMatchDemotion;
92 #endif
93
111 enum ULocMatchDirection {
117 ULOCMATCH_DIRECTION_WITH_ONE_WAY,
124 ULOCMATCH_DIRECTION_ONLY_TWO_WAY
125 };
126 #ifndef U_IN_DOXYGEN
127 typedef enum ULocMatchDirection ULocMatchDirection;
128 #endif
129
130 struct UHashtable;
131
132 U_NAMESPACE_BEGIN
133
134 struct LSR;
135
136 class LocaleDistance;
137 class LocaleLsrIterator;
138 class UVector;
139 class XLikelySubtags;
140
184 class U_COMMON_API LocaleMatcher : public UMemory {
185 public:
192 class U_COMMON_API Result : public UMemory {
193 public:
201 Result(Result &&src) U_NOEXCEPT;
202
208 ~Result();
209
217 Result &operator=(Result &&src) U_NOEXCEPT;
218
226 inline const Locale *getDesiredLocale() const { return desiredLocale; }
227
237 inline const Locale *getSupportedLocale() const { return supportedLocale; }
238
246 inline int32_t getDesiredIndex() const { return desiredIndex; }
247
258 inline int32_t getSupportedIndex() const { return supportedIndex; }
259
272 Locale makeResolvedLocale(UErrorCode &errorCode) const;
273
274 private:
275 Result(const Locale *desired, const Locale *supported,
276 int32_t desIndex, int32_t suppIndex, UBool owned) :
277 desiredLocale(desired), supportedLocale(supported),
278 desiredIndex(desIndex), supportedIndex(suppIndex),
279 desiredIsOwned(owned) {}
280
281 Result(const Result &other) = delete;
282 Result &operator=(const Result &other) = delete;
283
284 const Locale *desiredLocale;
285 const Locale *supportedLocale;
286 int32_t desiredIndex;
287 int32_t supportedIndex;
288 UBool desiredIsOwned;
289
290 friend class LocaleMatcher;
291 };
292
299 class U_COMMON_API Builder : public UMemory {
300 public:
307 Builder() {}
308
316 Builder(Builder &&src) U_NOEXCEPT;
317
323 ~Builder();
324
332 Builder &operator=(Builder &&src) U_NOEXCEPT;
333
345 Builder &setSupportedLocalesFromListString(StringPiece locales);
346
356 Builder &setSupportedLocales(Locale::Iterator &locales);
357
371 template<typename Iter>
372 Builder &setSupportedLocales(Iter begin, Iter end) {
373 if (U_FAILURE(errorCode_)) { return *this; }
374 clearSupportedLocales();
375 while (begin != end) {
376 addSupportedLocale(*begin++);
377 }
378 return *this;
379 }
380
396 template<typename Iter, typename Conv>
397 Builder &setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter) {
398 if (U_FAILURE(errorCode_)) { return *this; }
399 clearSupportedLocales();
400 while (begin != end) {
401 addSupportedLocale(converter(*begin++));
402 }
403 return *this;
404 }
405
414 Builder &addSupportedLocale(const Locale &locale);
415
416 #ifndef U_HIDE_DRAFT_API
417
425 Builder &setNoDefaultLocale();
426 #endif // U_HIDE_DRAFT_API
427
438 Builder &setDefaultLocale(const Locale *defaultLocale);
439
450 Builder &setFavorSubtag(ULocMatchFavorSubtag subtag);
451
460 Builder &setDemotionPerDesiredLocale(ULocMatchDemotion demotion);
461
470 Builder &setDirection(ULocMatchDirection direction) {
471 if (U_SUCCESS(errorCode_)) {
472 direction_ = direction;
473 }
474 return *this;
475 }
476
477 #ifndef U_HIDE_DRAFT_API
478
499 Builder &setMaxDistance(const Locale &desired, const Locale &supported);
500 #endif // U_HIDE_DRAFT_API
501
512 UBool copyErrorTo(UErrorCode &outErrorCode) const;
513
524 LocaleMatcher build(UErrorCode &errorCode) const;
525
526 private:
527 friend class LocaleMatcher;
528
529 Builder(const Builder &other) = delete;
530 Builder &operator=(const Builder &other) = delete;
531
532 void clearSupportedLocales();
533 bool ensureSupportedLocaleVector();
534
535 UErrorCode errorCode_ = U_ZERO_ERROR;
536 UVector *supportedLocales_ = nullptr;
537 int32_t thresholdDistance_ = -1;
538 ULocMatchDemotion demotion_ = ULOCMATCH_DEMOTION_REGION;
539 Locale *defaultLocale_ = nullptr;
540 bool withDefault_ = true;
541 ULocMatchFavorSubtag favor_ = ULOCMATCH_FAVOR_LANGUAGE;
542 ULocMatchDirection direction_ = ULOCMATCH_DIRECTION_WITH_ONE_WAY;
543 Locale *maxDistanceDesired_ = nullptr;
544 Locale *maxDistanceSupported_ = nullptr;
545 };
546
547 // FYI No public LocaleMatcher constructors in C++; use the Builder.
548
555 LocaleMatcher(LocaleMatcher &&src) U_NOEXCEPT;
556
561 ~LocaleMatcher();
562
571 LocaleMatcher &operator=(LocaleMatcher &&src) U_NOEXCEPT;
572
583 const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const;
584
595 const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
596
611 const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const;
612
625 Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const;
626
639 Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
640
641 #ifndef U_HIDE_DRAFT_API
642
655 UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
656 #endif // U_HIDE_DRAFT_API
657
658 #ifndef U_HIDE_INTERNAL_API
659
677 double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
678 #endif // U_HIDE_INTERNAL_API
679
680 private:
681 LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
682 LocaleMatcher(const LocaleMatcher &other) = delete;
683 LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
684
685 int32_t putIfAbsent(const LSR &lsr, int32_t i, int32_t suppLength, UErrorCode &errorCode);
686
687 int32_t getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
688
689 const XLikelySubtags &likelySubtags;
690 const LocaleDistance &localeDistance;
691 int32_t thresholdDistance;
692 int32_t demotionPerDesiredLocale;
693 ULocMatchFavorSubtag favorSubtag;
694 ULocMatchDirection direction;
695
696 // These are in input order.
697 const Locale ** supportedLocales;
698 LSR *lsrs;
699 int32_t supportedLocalesLength;
700 // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
701 UHashtable *supportedLsrToIndex; // Map<LSR, Integer>
702 // Array versions of the supportedLsrToIndex keys and values.
703 // The distance lookup loops over the supportedLSRs and returns the index of the best match.
704 const LSR **supportedLSRs;
705 int32_t *supportedIndexes;
706 int32_t supportedLSRsLength;
707 Locale *ownedDefaultLocale;
708 const Locale *defaultLocale;
709 };
710
711 U_NAMESPACE_END
712
713 #endif // U_SHOW_CPLUSPLUS_API
714 #endif // __LOCALEMATCHER_H__
icu::LocaleMatcher::Builder
LocaleMatcher builder.
Definition: localematcher.h:299
UHashtable
struct UHashtable UHashtable
Definition: msgfmt.h:43
ULOCMATCH_DIRECTION_ONLY_TWO_WAY
@ ULOCMATCH_DIRECTION_ONLY_TWO_WAY
Locale matching limited to two-way matches including e.g.
Definition: localematcher.h:124
icu::LocaleMatcher::Result
Data for the best-matching pair of a desired and a supported locale.
Definition: localematcher.h:192
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
ULocMatchDemotion
ULocMatchDemotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred.
Definition: localematcher.h:55
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
U_NOEXCEPT
#define U_NOEXCEPT
Definition: platform.h:529
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:258
icu::LocaleMatcher::Builder::setDirection
Builder & setDirection(ULocMatchDirection direction)
Option for whether to include or ignore one-way (fallback) match data.
Definition: localematcher.h:470
U_COMMON_API
#define U_COMMON_API
Definition: utypes.h:300
stringpiece.h
C++ API: StringPiece: Read-only byte string wrapper class.
icu::LocaleMatcher::Result::getDesiredLocale
const Locale * getDesiredLocale() const
Returns the best-matching desired locale.
Definition: localematcher.h:226
icu::LocaleMatcher::Builder::Builder
Builder()
Constructs a builder used in chaining parameters for building a LocaleMatcher.
Definition: localematcher.h:307
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:719
icu::Locale::Iterator
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1014
ULocMatchFavorSubtag
ULocMatchFavorSubtag
Builder option for whether the language subtag or the script subtag is most important.
Definition: localematcher.h:29
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
ULOCMATCH_DEMOTION_NONE
@ ULOCMATCH_DEMOTION_NONE
All desired locales are treated equally.
Definition: localematcher.h:61
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:115
ULocMatchDirection
ULocMatchDirection
Builder option for whether to include or ignore one-way (fallback) match data.
Definition: localematcher.h:111
icu::LocaleMatcher::Result::getSupportedLocale
const Locale * getSupportedLocale() const
Returns the best-matching supported locale.
Definition: localematcher.h:237
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:372
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:397
U_ZERO_ERROR
@ U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449
ULOCMATCH_FAVOR_LANGUAGE
@ ULOCMATCH_FAVOR_LANGUAGE
Language differences are most important, then script differences, then region differences.
Definition: localematcher.h:36
U_SUCCESS
#define U_SUCCESS(x)
Does the error code indicate success?
Definition: utypes.h:714
icu::LocaleMatcher
Immutable class that picks the best match between a user's desired locales and an application's suppo...
Definition: localematcher.h:184
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:246
ULOCMATCH_FAVOR_SCRIPT
@ ULOCMATCH_FAVOR_SCRIPT
Makes script differences matter relatively more than language differences.
Definition: localematcher.h:42
locid.h
C++ API: Locale ID object.
uobject.h
C++ API: Common ICU base class UObject.
icu::StringPiece
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
ULOCMATCH_DIRECTION_WITH_ONE_WAY
@ ULOCMATCH_DIRECTION_WITH_ONE_WAY
Locale matching includes one-way matches such as Breton→French.
Definition: localematcher.h:117
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
ULOCMATCH_DEMOTION_REGION
@ ULOCMATCH_DEMOTION_REGION
Earlier desired locales are preferred.
Definition: localematcher.h:88