ICU 67.1  67.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#License
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 
23 #ifndef U_FORCE_HIDE_DRAFT_API
24 
45 };
46 #ifndef U_IN_DOXYGEN
48 #endif
49 
91 };
92 #ifndef U_IN_DOXYGEN
94 #endif
95 
127 };
128 #ifndef U_IN_DOXYGEN
130 #endif
131 
132 struct UHashtable;
133 
134 U_NAMESPACE_BEGIN
135 
136 struct LSR;
137 
138 class LocaleDistance;
139 class LocaleLsrIterator;
140 class UVector;
141 class XLikelySubtags;
142 
187 public:
194  class U_COMMON_API Result : public UMemory {
195  public:
203  Result(Result &&src) U_NOEXCEPT;
204 
210  ~Result();
211 
219  Result &operator=(Result &&src) U_NOEXCEPT;
220 
221 #ifndef U_HIDE_DRAFT_API
222 
229  inline const Locale *getDesiredLocale() const { return desiredLocale; }
230 
240  inline const Locale *getSupportedLocale() const { return supportedLocale; }
241 
249  inline int32_t getDesiredIndex() const { return desiredIndex; }
250 
261  inline int32_t getSupportedIndex() const { return supportedIndex; }
262 
275  Locale makeResolvedLocale(UErrorCode &errorCode) const;
276 #endif // U_HIDE_DRAFT_API
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 
304  class U_COMMON_API Builder : public UMemory {
305  public:
312  Builder() {}
313 
321  Builder(Builder &&src) U_NOEXCEPT;
322 
328  ~Builder();
329 
337  Builder &operator=(Builder &&src) U_NOEXCEPT;
338 
339 #ifndef U_HIDE_DRAFT_API
340 
351  Builder &setSupportedLocalesFromListString(StringPiece locales);
352 
362  Builder &setSupportedLocales(Locale::Iterator &locales);
363 
377  template<typename Iter>
378  Builder &setSupportedLocales(Iter begin, Iter end) {
379  if (U_FAILURE(errorCode_)) { return *this; }
380  clearSupportedLocales();
381  while (begin != end) {
382  addSupportedLocale(*begin++);
383  }
384  return *this;
385  }
386 
402  template<typename Iter, typename Conv>
403  Builder &setSupportedLocalesViaConverter(Iter begin, Iter end, Conv converter) {
404  if (U_FAILURE(errorCode_)) { return *this; }
405  clearSupportedLocales();
406  while (begin != end) {
407  addSupportedLocale(converter(*begin++));
408  }
409  return *this;
410  }
411 
420  Builder &addSupportedLocale(const Locale &locale);
421 
430  Builder &setDefaultLocale(const Locale *defaultLocale);
431 
442  Builder &setFavorSubtag(ULocMatchFavorSubtag subtag);
443 
452  Builder &setDemotionPerDesiredLocale(ULocMatchDemotion demotion);
453 
463  if (U_SUCCESS(errorCode_)) {
464  direction_ = direction;
465  }
466  return *this;
467  }
468 
479  UBool copyErrorTo(UErrorCode &outErrorCode) const;
480 
491  LocaleMatcher build(UErrorCode &errorCode) const;
492 #endif // U_HIDE_DRAFT_API
493 
494  private:
495  friend class LocaleMatcher;
496 
497  Builder(const Builder &other) = delete;
498  Builder &operator=(const Builder &other) = delete;
499 
500  void clearSupportedLocales();
501  bool ensureSupportedLocaleVector();
502 
503  UErrorCode errorCode_ = U_ZERO_ERROR;
504  UVector *supportedLocales_ = nullptr;
505  int32_t thresholdDistance_ = -1;
507  Locale *defaultLocale_ = nullptr;
510  };
511 
512  // FYI No public LocaleMatcher constructors in C++; use the Builder.
513 
521 
526  ~LocaleMatcher();
527 
536  LocaleMatcher &operator=(LocaleMatcher &&src) U_NOEXCEPT;
537 
538 #ifndef U_HIDE_DRAFT_API
539 
549  const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const;
550 
561  const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
562 
577  const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const;
578 
591  Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const;
592 
605  Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const;
606 #endif // U_HIDE_DRAFT_API
607 
608 #ifndef U_HIDE_INTERNAL_API
609 
627  double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
628 #endif // U_HIDE_INTERNAL_API
629 
630 private:
631  LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
632  LocaleMatcher(const LocaleMatcher &other) = delete;
633  LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
634 
635  int32_t putIfAbsent(const LSR &lsr, int32_t i, int32_t suppLength, UErrorCode &errorCode);
636 
637  int32_t getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
638 
639  const XLikelySubtags &likelySubtags;
640  const LocaleDistance &localeDistance;
641  int32_t thresholdDistance;
642  int32_t demotionPerDesiredLocale;
643  ULocMatchFavorSubtag favorSubtag;
644  ULocMatchDirection direction;
645 
646  // These are in input order.
647  const Locale ** supportedLocales;
648  LSR *lsrs;
649  int32_t supportedLocalesLength;
650  // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
651  UHashtable *supportedLsrToIndex; // Map<LSR, Integer> stores index+1 because 0 is "not found"
652  // Array versions of the supportedLsrToIndex keys and values.
653  // The distance lookup loops over the supportedLSRs and returns the index of the best match.
654  const LSR **supportedLSRs;
655  int32_t *supportedIndexes;
656  int32_t supportedLSRsLength;
657  Locale *ownedDefaultLocale;
658  const Locale *defaultLocale;
659 };
660 
661 U_NAMESPACE_END
662 
663 #endif // U_FORCE_HIDE_DRAFT_API
664 #endif // U_SHOW_CPLUSPLUS_API
665 #endif // __LOCALEMATCHER_H__
int32_t getSupportedIndex() const
Returns the index of the best-matching supported locale in the constructor’s or builder’s input ord...
struct UHashtable UHashtable
Definition: msgfmt.h:43
All desired locales are treated equally.
Definition: localematcher.h:63
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:704
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:709
ULocMatchDemotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred...
Definition: localematcher.h:57
Makes script differences matter relatively more than language differences.
Definition: localematcher.h:44
Locale matching limited to two-way matches including e.g.
Builder & setSupportedLocales(Iter begin, Iter end)
Copies the supported locales from the begin/end range, preserving iteration order.
const Locale * getDesiredLocale() const
Returns the best-matching desired locale.
No error, no warning.
Definition: utypes.h:449
Earlier desired locales are preferred.
Definition: localematcher.h:90
A Locale iterator interface similar to a Java Iterator<Locale>.
Definition: locid.h:1013
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:31
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.
ULocMatchDirection
Builder 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.
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.
#define U_NOEXCEPT
"noexcept" 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:38
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
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.
Definition: umachine.h:261
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195