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 
43 };
44 #ifndef U_IN_DOXYGEN
46 #endif
47 
89 };
90 #ifndef U_IN_DOXYGEN
92 #endif
93 
125 };
126 #ifndef U_IN_DOXYGEN
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 
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 
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;
539  Locale *defaultLocale_ = nullptr;
540  bool withDefault_ = true;
543  Locale *maxDistanceDesired_ = nullptr;
544  Locale *maxDistanceSupported_ = nullptr;
545  };
546 
547  // FYI No public LocaleMatcher constructors in C++; use the Builder.
548 
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__
struct UHashtable UHashtable
Definition: msgfmt.h:43
All desired locales are treated equally.
Definition: localematcher.h:61
Builder & setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter)
Copies the supported locales from the begin/end range, preserving iteration order.
#define U_SUCCESS(x)
Does the error code indicate success?
Definition: utypes.h:714
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:719
ULocMatchDemotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred...
Definition: localematcher.h:55
Makes script differences matter relatively more than language differences.
Definition: localematcher.h:42
Locale matching limited to two-way matches including e.g.
No error, no warning.
Definition: utypes.h:449
Earlier desired locales are preferred.
Definition: localematcher.h:88
C++ API: StringPiece: Read-only byte string wrapper class.
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
Immutable class that picks the best match between a user&#39;s desired locales and an application&#39;s suppo...
Builder()
Constructs a builder used in chaining parameters for building a LocaleMatcher.
Builder & setDirection(ULocMatchDirection direction)
Option for whether to include or ignore one-way (fallback) match data.
int32_t getDesiredIndex() const
Returns the index of the best-matching desired locale in the input Iterable order.
ULocMatchDirection
Builder option for whether to include or ignore one-way (fallback) match data.
const Locale * getSupportedLocale() const
Returns the best-matching supported locale.
Data for the best-matching pair of a desired and a supported locale.
C++ API: Common ICU base class UObject.
const Locale * getDesiredLocale() const
Returns the best-matching desired locale.
#define U_NOEXCEPT
&quot;noexcept&quot; if supported, otherwise empty.
Definition: platform.h:529
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
C++ API: Locale ID object.
Language differences are most important, then script differences, then region differences.
Definition: localematcher.h:36
Basic definitions for ICU, for both C and C++ APIs.
#define U_COMMON_API
Set to export library symbols from inside the common library, and to import them from outside...
Definition: utypes.h:300
int32_t getSupportedIndex() const
Returns the index of the best-matching supported locale in the constructor’s or builder’s input order...
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
LocaleMatcher builder.
UMemory is the common ICU base class.
Definition: uobject.h:115
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195