ICU 68.2  68.2
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 
94 #ifndef U_FORCE_HIDE_DRAFT_API
95 
127 };
128 #ifndef U_IN_DOXYGEN
130 #endif
131 
132 #endif // U_FORCE_HIDE_DRAFT_API
133 
134 struct UHashtable;
135 
136 U_NAMESPACE_BEGIN
137 
138 struct LSR;
139 
140 class LocaleDistance;
141 class LocaleLsrIterator;
142 class UVector;
143 class XLikelySubtags;
144 
189 public:
196  class U_COMMON_API Result : public UMemory {
197  public:
205  Result(Result &&src) U_NOEXCEPT;
206 
212  ~Result();
213 
221  Result &operator=(Result &&src) U_NOEXCEPT;
222 
230  inline const Locale *getDesiredLocale() const { return desiredLocale; }
231 
241  inline const Locale *getSupportedLocale() const { return supportedLocale; }
242 
250  inline int32_t getDesiredIndex() const { return desiredIndex; }
251 
262  inline int32_t getSupportedIndex() const { return supportedIndex; }
263 
276  Locale makeResolvedLocale(UErrorCode &errorCode) const;
277 
278  private:
279  Result(const Locale *desired, const Locale *supported,
280  int32_t desIndex, int32_t suppIndex, UBool owned) :
281  desiredLocale(desired), supportedLocale(supported),
282  desiredIndex(desIndex), supportedIndex(suppIndex),
283  desiredIsOwned(owned) {}
284 
285  Result(const Result &other) = delete;
286  Result &operator=(const Result &other) = delete;
287 
288  const Locale *desiredLocale;
289  const Locale *supportedLocale;
290  int32_t desiredIndex;
291  int32_t supportedIndex;
292  UBool desiredIsOwned;
293 
294  friend class LocaleMatcher;
295  };
296 
303  class U_COMMON_API Builder : public UMemory {
304  public:
311  Builder() {}
312 
320  Builder(Builder &&src) U_NOEXCEPT;
321 
327  ~Builder();
328 
336  Builder &operator=(Builder &&src) U_NOEXCEPT;
337 
349  Builder &setSupportedLocalesFromListString(StringPiece locales);
350 
360  Builder &setSupportedLocales(Locale::Iterator &locales);
361 
375  template<typename Iter>
376  Builder &setSupportedLocales(Iter begin, Iter end) {
377  if (U_FAILURE(errorCode_)) { return *this; }
378  clearSupportedLocales();
379  while (begin != end) {
380  addSupportedLocale(*begin++);
381  }
382  return *this;
383  }
384 
400  template<typename Iter, typename Conv>
401  Builder &setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter) {
402  if (U_FAILURE(errorCode_)) { return *this; }
403  clearSupportedLocales();
404  while (begin != end) {
405  addSupportedLocale(converter(*begin++));
406  }
407  return *this;
408  }
409 
418  Builder &addSupportedLocale(const Locale &locale);
419 
420 #ifndef U_HIDE_DRAFT_API
421 
429  Builder &setNoDefaultLocale();
430 #endif // U_HIDE_DRAFT_API
431 
442  Builder &setDefaultLocale(const Locale *defaultLocale);
443 
454  Builder &setFavorSubtag(ULocMatchFavorSubtag subtag);
455 
464  Builder &setDemotionPerDesiredLocale(ULocMatchDemotion demotion);
465 
466 #ifndef U_HIDE_DRAFT_API
467 
476  if (U_SUCCESS(errorCode_)) {
477  direction_ = direction;
478  }
479  return *this;
480  }
481 #endif // U_HIDE_DRAFT_API
482 
483 #ifndef U_HIDE_DRAFT_API
484 
505  Builder &setMaxDistance(const Locale &desired, const Locale &supported);
506 #endif // U_HIDE_DRAFT_API
507 
518  UBool copyErrorTo(UErrorCode &outErrorCode) const;
519 
530  LocaleMatcher build(UErrorCode &errorCode) const;
531 
532  private:
533  friend class LocaleMatcher;
534 
535  Builder(const Builder &other) = delete;
536  Builder &operator=(const Builder &other) = delete;
537 
538  void clearSupportedLocales();
539  bool ensureSupportedLocaleVector();
540 
541  UErrorCode errorCode_ = U_ZERO_ERROR;
542  UVector *supportedLocales_ = nullptr;
543  int32_t thresholdDistance_ = -1;
545  Locale *defaultLocale_ = nullptr;
546  bool withDefault_ = true;
549  Locale *maxDistanceDesired_ = nullptr;
550  Locale *maxDistanceSupported_ = nullptr;
551  };
552 
553  // FYI No public LocaleMatcher constructors in C++; use the Builder.
554 
562 
567  ~LocaleMatcher();
568 
577  LocaleMatcher &operator=(LocaleMatcher &&src) U_NOEXCEPT;
578 
589  const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const;
590 
601  const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
602 
617  const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const;
618 
631  Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const;
632 
645  Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
646 
647 #ifndef U_HIDE_DRAFT_API
648 
661  UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
662 #endif // U_HIDE_DRAFT_API
663 
664 #ifndef U_HIDE_INTERNAL_API
665 
683  double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
684 #endif // U_HIDE_INTERNAL_API
685 
686 private:
687  LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
688  LocaleMatcher(const LocaleMatcher &other) = delete;
689  LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
690 
691  int32_t putIfAbsent(const LSR &lsr, int32_t i, int32_t suppLength, UErrorCode &errorCode);
692 
693  int32_t getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
694 
695  const XLikelySubtags &likelySubtags;
696  const LocaleDistance &localeDistance;
697  int32_t thresholdDistance;
698  int32_t demotionPerDesiredLocale;
699  ULocMatchFavorSubtag favorSubtag;
700  ULocMatchDirection direction;
701 
702  // These are in input order.
703  const Locale ** supportedLocales;
704  LSR *lsrs;
705  int32_t supportedLocalesLength;
706  // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
707  UHashtable *supportedLsrToIndex; // Map<LSR, Integer> stores index+1 because 0 is "not found"
708  // Array versions of the supportedLsrToIndex keys and values.
709  // The distance lookup loops over the supportedLSRs and returns the index of the best match.
710  const LSR **supportedLSRs;
711  int32_t *supportedIndexes;
712  int32_t supportedLSRsLength;
713  Locale *ownedDefaultLocale;
714  const Locale *defaultLocale;
715 };
716 
717 U_NAMESPACE_END
718 
719 #endif // U_SHOW_CPLUSPLUS_API
720 #endif // __LOCALEMATCHER_H__
icu::LocaleMatcher::Builder
LocaleMatcher builder.
Definition: localematcher.h:303
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:126
icu::LocaleMatcher::Result
Data for the best-matching pair of a desired and a supported locale.
Definition: localematcher.h:196
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:262
icu::LocaleMatcher::Builder::setDirection
Builder & setDirection(ULocMatchDirection direction)
Option for whether to include or ignore one-way (fallback) match data.
Definition: localematcher.h:475
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:230
icu::LocaleMatcher::Builder::Builder
Builder()
Constructs a builder used in chaining parameters for building a LocaleMatcher.
Definition: localematcher.h:311
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:1016
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:113
icu::LocaleMatcher::Result::getSupportedLocale
const Locale * getSupportedLocale() const
Returns the best-matching supported locale.
Definition: localematcher.h:241
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:376
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:401
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:188
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:250
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:119
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