ICU 74.1 74.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
43};
44#ifndef U_IN_DOXYGEN
46#endif
47
89};
90#ifndef U_IN_DOXYGEN
92#endif
93
126#ifndef U_IN_DOXYGEN
128#endif
129
130struct UHashtable;
131
132U_NAMESPACE_BEGIN
133
134struct LSR;
135
136class LocaleDistance;
137class LocaleLsrIterator;
138class UVector;
139class XLikelySubtags;
140
185public:
192 class U_COMMON_API Result : public UMemory {
193 public:
201 Result(Result &&src) noexcept;
202
209
217 Result &operator=(Result &&src) 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
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:
308
316 Builder(Builder &&src) noexcept;
317
324
332 Builder &operator=(Builder &&src) noexcept;
333
346
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
415
425
436 Builder &setDefaultLocale(const Locale *defaultLocale);
437
449
459
469 if (U_SUCCESS(errorCode_)) {
470 direction_ = matchDirection;
471 }
472 return *this;
473 }
474
496 Builder &setMaxDistance(const Locale &desired, const Locale &supported);
497
508 UBool copyErrorTo(UErrorCode &outErrorCode) const;
509
520 LocaleMatcher build(UErrorCode &errorCode) const;
521
522 private:
523 friend class LocaleMatcher;
524
525 Builder(const Builder &other) = delete;
526 Builder &operator=(const Builder &other) = delete;
527
528 void clearSupportedLocales();
529 bool ensureSupportedLocaleVector();
530
531 UErrorCode errorCode_ = U_ZERO_ERROR;
532 UVector *supportedLocales_ = nullptr;
533 int32_t thresholdDistance_ = -1;
535 Locale *defaultLocale_ = nullptr;
536 bool withDefault_ = true;
539 Locale *maxDistanceDesired_ = nullptr;
540 Locale *maxDistanceSupported_ = nullptr;
541 };
542
543 // FYI No public LocaleMatcher constructors in C++; use the Builder.
544
552
558
568
579 const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const;
580
591 const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
592
607 const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const;
608
621 Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const;
622
635 Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
636
650 UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
651
652#ifndef U_HIDE_INTERNAL_API
671 double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
672#endif // U_HIDE_INTERNAL_API
673
674private:
675 LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
676 LocaleMatcher(const LocaleMatcher &other) = delete;
677 LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
678
679 int32_t putIfAbsent(const LSR &lsr, int32_t i, int32_t suppLength, UErrorCode &errorCode);
680
681 int32_t getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
682
683 const XLikelySubtags &likelySubtags;
684 const LocaleDistance &localeDistance;
685 int32_t thresholdDistance;
686 int32_t demotionPerDesiredLocale;
687 ULocMatchFavorSubtag favorSubtag;
688 ULocMatchDirection direction;
689
690 // These are in input order.
691 const Locale ** supportedLocales;
692 LSR *lsrs;
693 int32_t supportedLocalesLength;
694 // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
695 UHashtable *supportedLsrToIndex; // Map<LSR, Integer>
696 // Array versions of the supportedLsrToIndex keys and values.
697 // The distance lookup loops over the supportedLSRs and returns the index of the best match.
698 const LSR **supportedLSRs;
699 int32_t *supportedIndexes;
700 int32_t supportedLSRsLength;
701 Locale *ownedDefaultLocale;
702 const Locale *defaultLocale;
703};
704
705U_NAMESPACE_END
706
707#endif // U_SHOW_CPLUSPLUS_API
708#endif // __LOCALEMATCHER_H__
LocaleMatcher builder.
Builder & setMaxDistance(const Locale &desired, const Locale &supported)
Sets the maximum distance for an acceptable match.
Builder(Builder &&src) noexcept
Move constructor; might modify the source.
Builder & setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter)
Copies the supported locales from the begin/end range, preserving iteration order.
Builder & operator=(Builder &&src) noexcept
Move assignment; might modify the source.
LocaleMatcher build(UErrorCode &errorCode) const
Builds and returns a new locale matcher.
Builder & setSupportedLocales(Locale::Iterator &locales)
Copies the supported locales, preserving iteration order.
Builder & setDefaultLocale(const Locale *defaultLocale)
Sets the default locale; if nullptr, or if it is not set explicitly, then the first supported locale ...
Builder & setDemotionPerDesiredLocale(ULocMatchDemotion demotion)
Option for whether all desired locales are treated equally or earlier ones are preferred (this is the...
Builder & setDirection(ULocMatchDirection matchDirection)
Option for whether to include or ignore one-way (fallback) match data.
Builder & addSupportedLocale(const Locale &locale)
Adds another supported locale.
Builder & setFavorSubtag(ULocMatchFavorSubtag subtag)
If ULOCMATCH_FAVOR_SCRIPT, then the language differences are smaller than script differences.
Builder & setSupportedLocalesFromListString(StringPiece locales)
Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0....
Builder & setNoDefaultLocale()
Sets no default locale.
Builder & setSupportedLocales(Iter begin, Iter end)
Copies the supported locales from the begin/end range, preserving iteration order.
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred while setting parameters.
Builder()
Constructs a builder used in chaining parameters for building a LocaleMatcher.
Data for the best-matching pair of a desired and a supported locale.
const Locale * getDesiredLocale() const
Returns the best-matching desired locale.
int32_t getSupportedIndex() const
Returns the index of the best-matching supported locale in the constructor’s or builder’s input order...
const Locale * getSupportedLocale() const
Returns the best-matching supported locale.
int32_t getDesiredIndex() const
Returns the index of the best-matching desired locale in the input Iterable order.
Locale makeResolvedLocale(UErrorCode &errorCode) const
Takes the best-matching supported locale and adds relevant fields of the best-matching desired locale...
Result(Result &&src) noexcept
Move constructor; might modify the source.
Result & operator=(Result &&src) noexcept
Move assignment; might modify the source.
Immutable class that picks the best match between a user's desired locales and an application's suppo...
const Locale * getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const
Returns the supported locale which best matches the desired locale.
LocaleMatcher(LocaleMatcher &&src) noexcept
Move copy constructor; might modify the source.
UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const
Returns true if the pair of locales matches acceptably.
Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const
Returns the best match between the desired locale and the supported locales.
Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const
Returns the best match between the desired and supported locales.
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,...
LocaleMatcher & operator=(LocaleMatcher &&src) noexcept
Move assignment operator; might modify the source.
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....
~LocaleMatcher()
Destructor.
const Locale * getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const
Returns the supported locale which best matches one of the desired locales.
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1017
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
UMemory is the common ICU base class.
Definition: uobject.h:115
ULocMatchDemotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred.
Definition: localematcher.h:55
@ ULOCMATCH_DEMOTION_REGION
Earlier desired locales are preferred.
Definition: localematcher.h:88
@ ULOCMATCH_DEMOTION_NONE
All desired locales are treated equally.
Definition: localematcher.h:61
ULocMatchDirection
Builder option for whether to include or ignore one-way (fallback) match data.
@ ULOCMATCH_DIRECTION_ONLY_TWO_WAY
Locale matching limited to two-way matches including e.g.
@ ULOCMATCH_DIRECTION_WITH_ONE_WAY
Locale matching includes one-way matches such as Breton→French.
ULocMatchFavorSubtag
Builder option for whether the language subtag or the script subtag is most important.
Definition: localematcher.h:29
@ ULOCMATCH_FAVOR_SCRIPT
Makes script differences matter relatively more than language differences.
Definition: localematcher.h:42
@ ULOCMATCH_FAVOR_LANGUAGE
Language differences are most important, then script differences, then region differences.
Definition: localematcher.h:36
C++ API: Locale ID object.
struct UHashtable UHashtable
Definition: msgfmt.h:43
C++ API: StringPiece: Read-only byte string wrapper class.
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
C++ API: Common ICU base class UObject.
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
@ U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:717
#define U_SUCCESS(x)
Does the error code indicate success?
Definition: utypes.h:712
#define U_COMMON_API
Set to export library symbols from inside the common library, and to import them from outside.
Definition: utypes.h:300