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 | |
18 | /** |
19 | * \file |
20 | * \brief C++ API: Locale matcher: User's desired locales vs. application's supported locales. |
21 | */ |
22 | |
23 | /** |
24 | * Builder option for whether the language subtag or the script subtag is most important. |
25 | * |
26 | * @see LocaleMatcher::Builder#setFavorSubtag(ULocMatchFavorSubtag) |
27 | * @stable ICU 65 |
28 | */ |
29 | enum ULocMatchFavorSubtag { |
30 | /** |
31 | * Language differences are most important, then script differences, then region differences. |
32 | * (This is the default behavior.) |
33 | * |
34 | * @stable ICU 65 |
35 | */ |
36 | ULOCMATCH_FAVOR_LANGUAGE, |
37 | /** |
38 | * Makes script differences matter relatively more than language differences. |
39 | * |
40 | * @stable ICU 65 |
41 | */ |
42 | ULOCMATCH_FAVOR_SCRIPT |
43 | }; |
44 | #ifndef U_IN_DOXYGEN |
45 | typedef enum ULocMatchFavorSubtag ULocMatchFavorSubtag; |
46 | #endif |
47 | |
48 | /** |
49 | * Builder option for whether all desired locales are treated equally or |
50 | * earlier ones are preferred. |
51 | * |
52 | * @see LocaleMatcher::Builder#setDemotionPerDesiredLocale(ULocMatchDemotion) |
53 | * @stable ICU 65 |
54 | */ |
55 | enum ULocMatchDemotion { |
56 | /** |
57 | * All desired locales are treated equally. |
58 | * |
59 | * @stable ICU 65 |
60 | */ |
61 | ULOCMATCH_DEMOTION_NONE, |
62 | /** |
63 | * Earlier desired locales are preferred. |
64 | * |
65 | * <p>From each desired locale to the next, |
66 | * the distance to any supported locale is increased by an additional amount |
67 | * which is at least as large as most region mismatches. |
68 | * A later desired locale has to have a better match with some supported locale |
69 | * due to more than merely having the same region subtag. |
70 | * |
71 | * <p>For example: <code>Supported={en, sv} desired=[en-GB, sv]</code> |
72 | * yields <code>Result(en-GB, en)</code> because |
73 | * with the demotion of sv its perfect match is no better than |
74 | * the region distance between the earlier desired locale en-GB and en=en-US. |
75 | * |
76 | * <p>Notes: |
77 | * <ul> |
78 | * <li>In some cases, language and/or script differences can be as small as |
79 | * the typical region difference. (Example: sr-Latn vs. sr-Cyrl) |
80 | * <li>It is possible for certain region differences to be larger than usual, |
81 | * and larger than the demotion. |
82 | * (As of CLDR 35 there is no such case, but |
83 | * this is possible in future versions of the data.) |
84 | * </ul> |
85 | * |
86 | * @stable ICU 65 |
87 | */ |
88 | ULOCMATCH_DEMOTION_REGION |
89 | }; |
90 | #ifndef U_IN_DOXYGEN |
91 | typedef enum ULocMatchDemotion ULocMatchDemotion; |
92 | #endif |
93 | |
94 | /** |
95 | * Builder option for whether to include or ignore one-way (fallback) match data. |
96 | * The LocaleMatcher uses CLDR languageMatch data which includes fallback (oneway=true) entries. |
97 | * Sometimes it is desirable to ignore those. |
98 | * |
99 | * <p>For example, consider a web application with the UI in a given language, |
100 | * with a link to another, related web app. |
101 | * The link should include the UI language, and the target server may also use |
102 | * the client’s Accept-Language header data. |
103 | * The target server has its own list of supported languages. |
104 | * One may want to favor UI language consistency, that is, |
105 | * if there is a decent match for the original UI language, we want to use it, |
106 | * but not if it is merely a fallback. |
107 | * |
108 | * @see LocaleMatcher::Builder#setDirection(ULocMatchDirection) |
109 | * @stable ICU 67 |
110 | */ |
111 | enum ULocMatchDirection { |
112 | /** |
113 | * Locale matching includes one-way matches such as Breton→French. (default) |
114 | * |
115 | * @stable ICU 67 |
116 | */ |
117 | ULOCMATCH_DIRECTION_WITH_ONE_WAY, |
118 | /** |
119 | * Locale matching limited to two-way matches including e.g. Danish↔Norwegian |
120 | * but ignoring one-way matches. |
121 | * |
122 | * @stable ICU 67 |
123 | */ |
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 | |
141 | /** |
142 | * Immutable class that picks the best match between a user's desired locales and |
143 | * an application's supported locales. |
144 | * Movable but not copyable. |
145 | * |
146 | * <p>Example: |
147 | * <pre> |
148 | * UErrorCode errorCode = U_ZERO_ERROR; |
149 | * LocaleMatcher matcher = LocaleMatcher::Builder().setSupportedLocales("fr, en-GB, en").build(errorCode); |
150 | * Locale *bestSupported = matcher.getBestLocale(Locale.US, errorCode); // "en" |
151 | * </pre> |
152 | * |
153 | * <p>A matcher takes into account when languages are close to one another, |
154 | * such as Danish and Norwegian, |
155 | * and when regional variants are close, like en-GB and en-AU as opposed to en-US. |
156 | * |
157 | * <p>If there are multiple supported locales with the same (language, script, region) |
158 | * likely subtags, then the current implementation returns the first of those locales. |
159 | * It ignores variant subtags (except for pseudolocale variants) and extensions. |
160 | * This may change in future versions. |
161 | * |
162 | * <p>For example, the current implementation does not distinguish between |
163 | * de, de-DE, de-Latn, de-1901, de-u-co-phonebk. |
164 | * |
165 | * <p>If you prefer one equivalent locale over another, then provide only the preferred one, |
166 | * or place it earlier in the list of supported locales. |
167 | * |
168 | * <p>Otherwise, the order of supported locales may have no effect on the best-match results. |
169 | * The current implementation compares each desired locale with supported locales |
170 | * in the following order: |
171 | * 1. Default locale, if supported; |
172 | * 2. CLDR "paradigm locales" like en-GB and es-419; |
173 | * 3. other supported locales. |
174 | * This may change in future versions. |
175 | * |
176 | * <p>Often a product will just need one matcher instance, built with the languages |
177 | * that it supports. However, it may want multiple instances with different |
178 | * default languages based on additional information, such as the domain. |
179 | * |
180 | * <p>This class is not intended for public subclassing. |
181 | * |
182 | * @stable ICU 65 |
183 | */ |
184 | class U_COMMON_API LocaleMatcher : public UMemory { |
185 | public: |
186 | /** |
187 | * Data for the best-matching pair of a desired and a supported locale. |
188 | * Movable but not copyable. |
189 | * |
190 | * @stable ICU 65 |
191 | */ |
192 | class U_COMMON_API Result : public UMemory { |
193 | public: |
194 | /** |
195 | * Move constructor; might modify the source. |
196 | * This object will have the same contents that the source object had. |
197 | * |
198 | * @param src Result to move contents from. |
199 | * @stable ICU 65 |
200 | */ |
201 | Result(Result &&src) noexcept; |
202 | |
203 | /** |
204 | * Destructor. |
205 | * |
206 | * @stable ICU 65 |
207 | */ |
208 | ~Result(); |
209 | |
210 | /** |
211 | * Move assignment; might modify the source. |
212 | * This object will have the same contents that the source object had. |
213 | * |
214 | * @param src Result to move contents from. |
215 | * @stable ICU 65 |
216 | */ |
217 | Result &operator=(Result &&src) noexcept; |
218 | |
219 | /** |
220 | * Returns the best-matching desired locale. |
221 | * nullptr if the list of desired locales is empty or if none matched well enough. |
222 | * |
223 | * @return the best-matching desired locale, or nullptr. |
224 | * @stable ICU 65 |
225 | */ |
226 | inline const Locale *getDesiredLocale() const { return desiredLocale; } |
227 | |
228 | /** |
229 | * Returns the best-matching supported locale. |
230 | * If none matched well enough, this is the default locale. |
231 | * The default locale is nullptr if Builder::setNoDefaultLocale() was called, |
232 | * or if the list of supported locales is empty and no explicit default locale is set. |
233 | * |
234 | * @return the best-matching supported locale, or nullptr. |
235 | * @stable ICU 65 |
236 | */ |
237 | inline const Locale *getSupportedLocale() const { return supportedLocale; } |
238 | |
239 | /** |
240 | * Returns the index of the best-matching desired locale in the input Iterable order. |
241 | * -1 if the list of desired locales is empty or if none matched well enough. |
242 | * |
243 | * @return the index of the best-matching desired locale, or -1. |
244 | * @stable ICU 65 |
245 | */ |
246 | inline int32_t getDesiredIndex() const { return desiredIndex; } |
247 | |
248 | /** |
249 | * Returns the index of the best-matching supported locale in the |
250 | * constructor’s or builder’s input order (“set” Collection plus “added” locales). |
251 | * If the matcher was built from a locale list string, then the iteration order is that |
252 | * of a LocalePriorityList built from the same string. |
253 | * -1 if the list of supported locales is empty or if none matched well enough. |
254 | * |
255 | * @return the index of the best-matching supported locale, or -1. |
256 | * @stable ICU 65 |
257 | */ |
258 | inline int32_t getSupportedIndex() const { return supportedIndex; } |
259 | |
260 | /** |
261 | * Takes the best-matching supported locale and adds relevant fields of the |
262 | * best-matching desired locale, such as the -t- and -u- extensions. |
263 | * May replace some fields of the supported locale. |
264 | * The result is the locale that should be used for date and number formatting, collation, etc. |
265 | * Returns the root locale if getSupportedLocale() returns nullptr. |
266 | * |
267 | * <p>Example: desired=ar-SA-u-nu-latn, supported=ar-EG, resolved locale=ar-SA-u-nu-latn |
268 | * |
269 | * @return a locale combining the best-matching desired and supported locales. |
270 | * @stable ICU 65 |
271 | */ |
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 | |
293 | /** |
294 | * LocaleMatcher builder. |
295 | * Movable but not copyable. |
296 | * |
297 | * @stable ICU 65 |
298 | */ |
299 | class U_COMMON_API Builder : public UMemory { |
300 | public: |
301 | /** |
302 | * Constructs a builder used in chaining parameters for building a LocaleMatcher. |
303 | * |
304 | * @return a new Builder object |
305 | * @stable ICU 65 |
306 | */ |
307 | Builder() {} |
308 | |
309 | /** |
310 | * Move constructor; might modify the source. |
311 | * This builder will have the same contents that the source builder had. |
312 | * |
313 | * @param src Builder to move contents from. |
314 | * @stable ICU 65 |
315 | */ |
316 | Builder(Builder &&src) noexcept; |
317 | |
318 | /** |
319 | * Destructor. |
320 | * |
321 | * @stable ICU 65 |
322 | */ |
323 | ~Builder(); |
324 | |
325 | /** |
326 | * Move assignment; might modify the source. |
327 | * This builder will have the same contents that the source builder had. |
328 | * |
329 | * @param src Builder to move contents from. |
330 | * @stable ICU 65 |
331 | */ |
332 | Builder &operator=(Builder &&src) noexcept; |
333 | |
334 | /** |
335 | * Parses an Accept-Language string |
336 | * (<a href="https://tools.ietf.org/html/rfc2616#section-14.4">RFC 2616 Section 14.4</a>), |
337 | * such as "af, en, fr;q=0.9", and sets the supported locales accordingly. |
338 | * Allows whitespace in more places but does not allow "*". |
339 | * Clears any previously set/added supported locales first. |
340 | * |
341 | * @param locales the Accept-Language string of locales to set |
342 | * @return this Builder object |
343 | * @stable ICU 65 |
344 | */ |
345 | Builder &setSupportedLocalesFromListString(StringPiece locales); |
346 | |
347 | /** |
348 | * Copies the supported locales, preserving iteration order. |
349 | * Clears any previously set/added supported locales first. |
350 | * Duplicates are allowed, and are not removed. |
351 | * |
352 | * @param locales the list of locale |
353 | * @return this Builder object |
354 | * @stable ICU 65 |
355 | */ |
356 | Builder &setSupportedLocales(Locale::Iterator &locales); |
357 | |
358 | /** |
359 | * Copies the supported locales from the begin/end range, preserving iteration order. |
360 | * Clears any previously set/added supported locales first. |
361 | * Duplicates are allowed, and are not removed. |
362 | * |
363 | * Each of the iterator parameter values must be an |
364 | * input iterator whose value is convertible to const Locale &. |
365 | * |
366 | * @param begin Start of range. |
367 | * @param end Exclusive end of range. |
368 | * @return this Builder object |
369 | * @stable ICU 65 |
370 | */ |
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 | |
381 | /** |
382 | * Copies the supported locales from the begin/end range, preserving iteration order. |
383 | * Calls the converter to convert each *begin to a Locale or const Locale &. |
384 | * Clears any previously set/added supported locales first. |
385 | * Duplicates are allowed, and are not removed. |
386 | * |
387 | * Each of the iterator parameter values must be an |
388 | * input iterator whose value is convertible to const Locale &. |
389 | * |
390 | * @param begin Start of range. |
391 | * @param end Exclusive end of range. |
392 | * @param converter Converter from *begin to const Locale & or compatible. |
393 | * @return this Builder object |
394 | * @stable ICU 65 |
395 | */ |
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 | |
406 | /** |
407 | * Adds another supported locale. |
408 | * Duplicates are allowed, and are not removed. |
409 | * |
410 | * @param locale another locale |
411 | * @return this Builder object |
412 | * @stable ICU 65 |
413 | */ |
414 | Builder &addSupportedLocale(const Locale &locale); |
415 | |
416 | /** |
417 | * Sets no default locale. |
418 | * There will be no explicit or implicit default locale. |
419 | * If there is no good match, then the matcher will return nullptr for the |
420 | * best supported locale. |
421 | * |
422 | * @stable ICU 68 |
423 | */ |
424 | Builder &setNoDefaultLocale(); |
425 | |
426 | /** |
427 | * Sets the default locale; if nullptr, or if it is not set explicitly, |
428 | * then the first supported locale is used as the default locale. |
429 | * There is no default locale at all (nullptr will be returned instead) |
430 | * if setNoDefaultLocale() is called. |
431 | * |
432 | * @param defaultLocale the default locale (will be copied) |
433 | * @return this Builder object |
434 | * @stable ICU 65 |
435 | */ |
436 | Builder &setDefaultLocale(const Locale *defaultLocale); |
437 | |
438 | /** |
439 | * If ULOCMATCH_FAVOR_SCRIPT, then the language differences are smaller than script |
440 | * differences. |
441 | * This is used in situations (such as maps) where |
442 | * it is better to fall back to the same script than a similar language. |
443 | * |
444 | * @param subtag the subtag to favor |
445 | * @return this Builder object |
446 | * @stable ICU 65 |
447 | */ |
448 | Builder &setFavorSubtag(ULocMatchFavorSubtag subtag); |
449 | |
450 | /** |
451 | * Option for whether all desired locales are treated equally or |
452 | * earlier ones are preferred (this is the default). |
453 | * |
454 | * @param demotion the demotion per desired locale to set. |
455 | * @return this Builder object |
456 | * @stable ICU 65 |
457 | */ |
458 | Builder &setDemotionPerDesiredLocale(ULocMatchDemotion demotion); |
459 | |
460 | /** |
461 | * Option for whether to include or ignore one-way (fallback) match data. |
462 | * By default, they are included. |
463 | * |
464 | * @param matchDirection the match direction to set. |
465 | * @return this Builder object |
466 | * @stable ICU 67 |
467 | */ |
468 | Builder &setDirection(ULocMatchDirection matchDirection) { |
469 | if (U_SUCCESS(errorCode_)) { |
470 | direction_ = matchDirection; |
471 | } |
472 | return *this; |
473 | } |
474 | |
475 | /** |
476 | * Sets the maximum distance for an acceptable match. |
477 | * The matcher will return a match for a pair of locales only if |
478 | * they match at least as well as the pair given here. |
479 | * |
480 | * For example, setMaxDistance(en-US, en-GB) limits matches to ones where the |
481 | * (desired, support) locales have a distance no greater than a region subtag difference. |
482 | * This is much stricter than the CLDR default. |
483 | * |
484 | * The details of locale matching are subject to changes in |
485 | * CLDR data and in the algorithm. |
486 | * Specifying a maximum distance in relative terms via a sample pair of locales |
487 | * insulates from changes that affect all distance metrics similarly, |
488 | * but some changes will necessarily affect relative distances between |
489 | * different pairs of locales. |
490 | * |
491 | * @param desired the desired locale for distance comparison. |
492 | * @param supported the supported locale for distance comparison. |
493 | * @return this Builder object |
494 | * @stable ICU 68 |
495 | */ |
496 | Builder &setMaxDistance(const Locale &desired, const Locale &supported); |
497 | |
498 | /** |
499 | * Sets the UErrorCode if an error occurred while setting parameters. |
500 | * Preserves older error codes in the outErrorCode. |
501 | * |
502 | * @param outErrorCode Set to an error code if it does not contain one already |
503 | * and an error occurred while setting parameters. |
504 | * Otherwise unchanged. |
505 | * @return true if U_FAILURE(outErrorCode) |
506 | * @stable ICU 65 |
507 | */ |
508 | UBool copyErrorTo(UErrorCode &outErrorCode) const; |
509 | |
510 | /** |
511 | * Builds and returns a new locale matcher. |
512 | * This builder can continue to be used. |
513 | * |
514 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
515 | * or else the function returns immediately. Check for U_FAILURE() |
516 | * on output or use with function chaining. (See User Guide for details.) |
517 | * @return LocaleMatcher |
518 | * @stable ICU 65 |
519 | */ |
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; |
534 | ULocMatchDemotion demotion_ = ULOCMATCH_DEMOTION_REGION; |
535 | Locale *defaultLocale_ = nullptr; |
536 | bool withDefault_ = true; |
537 | ULocMatchFavorSubtag favor_ = ULOCMATCH_FAVOR_LANGUAGE; |
538 | ULocMatchDirection direction_ = ULOCMATCH_DIRECTION_WITH_ONE_WAY; |
539 | Locale *maxDistanceDesired_ = nullptr; |
540 | Locale *maxDistanceSupported_ = nullptr; |
541 | }; |
542 | |
543 | // FYI No public LocaleMatcher constructors in C++; use the Builder. |
544 | |
545 | /** |
546 | * Move copy constructor; might modify the source. |
547 | * This matcher will have the same settings that the source matcher had. |
548 | * @param src source matcher |
549 | * @stable ICU 65 |
550 | */ |
551 | LocaleMatcher(LocaleMatcher &&src) noexcept; |
552 | |
553 | /** |
554 | * Destructor. |
555 | * @stable ICU 65 |
556 | */ |
557 | ~LocaleMatcher(); |
558 | |
559 | /** |
560 | * Move assignment operator; might modify the source. |
561 | * This matcher will have the same settings that the source matcher had. |
562 | * The behavior is undefined if *this and src are the same object. |
563 | * @param src source matcher |
564 | * @return *this |
565 | * @stable ICU 65 |
566 | */ |
567 | LocaleMatcher &operator=(LocaleMatcher &&src) noexcept; |
568 | |
569 | /** |
570 | * Returns the supported locale which best matches the desired locale. |
571 | * |
572 | * @param desiredLocale Typically a user's language. |
573 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
574 | * or else the function returns immediately. Check for U_FAILURE() |
575 | * on output or use with function chaining. (See User Guide for details.) |
576 | * @return the best-matching supported locale. |
577 | * @stable ICU 65 |
578 | */ |
579 | const Locale *getBestMatch(const Locale &desiredLocale, UErrorCode &errorCode) const; |
580 | |
581 | /** |
582 | * Returns the supported locale which best matches one of the desired locales. |
583 | * |
584 | * @param desiredLocales Typically a user's languages, in order of preference (descending). |
585 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
586 | * or else the function returns immediately. Check for U_FAILURE() |
587 | * on output or use with function chaining. (See User Guide for details.) |
588 | * @return the best-matching supported locale. |
589 | * @stable ICU 65 |
590 | */ |
591 | const Locale *getBestMatch(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const; |
592 | |
593 | /** |
594 | * Parses an Accept-Language string |
595 | * (<a href="https://tools.ietf.org/html/rfc2616#section-14.4">RFC 2616 Section 14.4</a>), |
596 | * such as "af, en, fr;q=0.9", |
597 | * and returns the supported locale which best matches one of the desired locales. |
598 | * Allows whitespace in more places but does not allow "*". |
599 | * |
600 | * @param desiredLocaleList Typically a user's languages, as an Accept-Language string. |
601 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
602 | * or else the function returns immediately. Check for U_FAILURE() |
603 | * on output or use with function chaining. (See User Guide for details.) |
604 | * @return the best-matching supported locale. |
605 | * @stable ICU 65 |
606 | */ |
607 | const Locale *getBestMatchForListString(StringPiece desiredLocaleList, UErrorCode &errorCode) const; |
608 | |
609 | /** |
610 | * Returns the best match between the desired locale and the supported locales. |
611 | * If the result's desired locale is not nullptr, then it is the address of the input locale. |
612 | * It has not been cloned. |
613 | * |
614 | * @param desiredLocale Typically a user's language. |
615 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
616 | * or else the function returns immediately. Check for U_FAILURE() |
617 | * on output or use with function chaining. (See User Guide for details.) |
618 | * @return the best-matching pair of the desired and a supported locale. |
619 | * @stable ICU 65 |
620 | */ |
621 | Result getBestMatchResult(const Locale &desiredLocale, UErrorCode &errorCode) const; |
622 | |
623 | /** |
624 | * Returns the best match between the desired and supported locales. |
625 | * If the result's desired locale is not nullptr, then it is a clone of |
626 | * the best-matching desired locale. The Result object owns the clone. |
627 | * |
628 | * @param desiredLocales Typically a user's languages, in order of preference (descending). |
629 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
630 | * or else the function returns immediately. Check for U_FAILURE() |
631 | * on output or use with function chaining. (See User Guide for details.) |
632 | * @return the best-matching pair of a desired and a supported locale. |
633 | * @stable ICU 65 |
634 | */ |
635 | Result getBestMatchResult(Locale::Iterator &desiredLocales, UErrorCode &errorCode) const; |
636 | |
637 | /** |
638 | * Returns true if the pair of locales matches acceptably. |
639 | * This is influenced by Builder options such as setDirection(), setFavorSubtag(), |
640 | * and setMaxDistance(). |
641 | * |
642 | * @param desired The desired locale. |
643 | * @param supported The supported locale. |
644 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
645 | * or else the function returns immediately. Check for U_FAILURE() |
646 | * on output or use with function chaining. (See User Guide for details.) |
647 | * @return true if the pair of locales matches acceptably. |
648 | * @stable ICU 68 |
649 | */ |
650 | UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const; |
651 | |
652 | #ifndef U_HIDE_INTERNAL_API |
653 | /** |
654 | * Returns a fraction between 0 and 1, where 1 means that the languages are a |
655 | * perfect match, and 0 means that they are completely different. |
656 | * |
657 | * <p>This is mostly an implementation detail, and the precise values may change over time. |
658 | * The implementation may use either the maximized forms or the others ones, or both. |
659 | * The implementation may or may not rely on the forms to be consistent with each other. |
660 | * |
661 | * <p>Callers should construct and use a matcher rather than match pairs of locales directly. |
662 | * |
663 | * @param desired Desired locale. |
664 | * @param supported Supported locale. |
665 | * @param errorCode ICU error code. Its input value must pass the U_SUCCESS() test, |
666 | * or else the function returns immediately. Check for U_FAILURE() |
667 | * on output or use with function chaining. (See User Guide for details.) |
668 | * @return value between 0 and 1, inclusive. |
669 | * @internal (has a known user) |
670 | */ |
671 | double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const; |
672 | #endif // U_HIDE_INTERNAL_API |
673 | |
674 | private: |
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 | |
705 | U_NAMESPACE_END |
706 | |
707 | #endif // U_SHOW_CPLUSPLUS_API |
708 | #endif // __LOCALEMATCHER_H__ |
709 | |