localematcher.h

Go to the documentation of this file.

// © 2019 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
 
// localematcher.h
// created: 2019may08 Markus W. Scherer
 
#ifndef __LOCALEMATCHER_H__
#define __LOCALEMATCHER_H__
 
#include "unicode/utypes.h"
 
#if U_SHOW_CPLUSPLUS_API
 
#include <optional>
 
#include "unicode/locid.h"
#include "unicode/stringpiece.h"
#include "unicode/uobject.h"


enum ULocMatchFavorSubtag {
    ULOCMATCH_FAVOR_LANGUAGE,
    ULOCMATCH_FAVOR_SCRIPT
};
#ifndef U_IN_DOXYGEN
typedef enum ULocMatchFavorSubtag ULocMatchFavorSubtag;
#endif

enum ULocMatchDemotion {
    ULOCMATCH_DEMOTION_NONE,
    ULOCMATCH_DEMOTION_REGION
};
#ifndef U_IN_DOXYGEN
typedef enum ULocMatchDemotion ULocMatchDemotion;
#endif

enum ULocMatchDirection {
    ULOCMATCH_DIRECTION_WITH_ONE_WAY,
    ULOCMATCH_DIRECTION_ONLY_TWO_WAY
};
#ifndef U_IN_DOXYGEN
typedef enum ULocMatchDirection ULocMatchDirection;
#endif
 
struct UHashtable;
 
U_NAMESPACE_BEGIN
 
struct LSR;
 
class LikelySubtags;
class LocaleDistance;
class LocaleLsrIterator;
class UVector;

class U_COMMON_API LocaleMatcher : public UMemory {
public:
    class U_COMMON_API Result : public UMemory {
    public:
        Result(Result &&src) noexcept;

        ~Result();

        Result& operator=(Result&& src) noexcept U_LIFETIME_BOUND;

        inline const Locale* getDesiredLocale() const U_LIFETIME_BOUND { return desiredLocale; }

        inline const Locale* getSupportedLocale() const U_LIFETIME_BOUND { return supportedLocale; }

        inline int32_t getDesiredIndex() const { return desiredIndex; }

        inline int32_t getSupportedIndex() const { return supportedIndex; }

        Locale makeResolvedLocale(UErrorCode &errorCode) const;
 
    private:
        Result(const Locale *desired, const Locale *supported,
               int32_t desIndex, int32_t suppIndex, UBool owned) :
                desiredLocale(desired), supportedLocale(supported),
                desiredIndex(desIndex), supportedIndex(suppIndex),
                desiredIsOwned(owned) {}
 
        Result(const Result &other) = delete;
        Result &operator=(const Result &other) = delete;
 
        const Locale *desiredLocale;
        const Locale *supportedLocale;
        int32_t desiredIndex;
        int32_t supportedIndex;
        UBool desiredIsOwned;
 
        friend class LocaleMatcher;
    };

    class U_COMMON_API Builder : public UMemory {
    public:
        Builder() {}

        Builder(Builder &&src) noexcept;

        ~Builder();

        Builder& operator=(Builder&& src) noexcept U_LIFETIME_BOUND;

        Builder& setSupportedLocalesFromListString(StringPiece locales) U_LIFETIME_BOUND;

        Builder& setSupportedLocales(Locale::Iterator& locales) U_LIFETIME_BOUND;

        template <typename Iter>
        Builder& setSupportedLocales(Iter begin, Iter end) U_LIFETIME_BOUND {
            if (U_FAILURE(errorCode_)) { return *this; }
            clearSupportedLocales();
            while (begin != end) {
                addSupportedLocale(*begin++);
            }
            return *this;
        }

        template <typename Iter, typename Conv>
        Builder& setSupportedLocalesViaConverter(Iter begin, Iter end,
                                                 Conv converter) U_LIFETIME_BOUND {
            if (U_FAILURE(errorCode_)) { return *this; }
            clearSupportedLocales();
            while (begin != end) {
                addSupportedLocale(converter(*begin++));
            }
            return *this;
        }

        Builder& addSupportedLocale(const Locale& locale) U_LIFETIME_BOUND;

        Builder& setNoDefaultLocale() U_LIFETIME_BOUND;

        Builder& setDefaultLocale(const Locale* defaultLocale) U_LIFETIME_BOUND;

        Builder& setFavorSubtag(ULocMatchFavorSubtag subtag) U_LIFETIME_BOUND;

        Builder& setDemotionPerDesiredLocale(ULocMatchDemotion demotion) U_LIFETIME_BOUND;

        Builder& setDirection(ULocMatchDirection matchDirection) U_LIFETIME_BOUND {
            if (U_SUCCESS(errorCode_)) {
                direction_ = matchDirection;
            }
            return *this;
        }

        Builder& setMaxDistance(const Locale& desired, const Locale& supported) U_LIFETIME_BOUND;

        UBool copyErrorTo(UErrorCode &outErrorCode) const;

        LocaleMatcher build(UErrorCode &errorCode) const;
 
    private:
        friend class LocaleMatcher;
 
        Builder(const Builder &other) = delete;
        Builder &operator=(const Builder &other) = delete;
 
        void clearSupportedLocales();
        bool ensureSupportedLocaleVector();
 
        UErrorCode errorCode_ = U_ZERO_ERROR;
        UVector *supportedLocales_ = nullptr;
        int32_t thresholdDistance_ = -1;
        ULocMatchDemotion demotion_ = ULOCMATCH_DEMOTION_REGION;
        Locale *defaultLocale_ = nullptr;
        bool withDefault_ = true;
        ULocMatchFavorSubtag favor_ = ULOCMATCH_FAVOR_LANGUAGE;
        ULocMatchDirection direction_ = ULOCMATCH_DIRECTION_WITH_ONE_WAY;
        Locale *maxDistanceDesired_ = nullptr;
        Locale *maxDistanceSupported_ = nullptr;
    };
 
    // FYI No public LocaleMatcher constructors in C++; use the Builder.

    LocaleMatcher(LocaleMatcher &&src) noexcept;

    ~LocaleMatcher();

    LocaleMatcher& operator=(LocaleMatcher&& src) noexcept U_LIFETIME_BOUND;

    const Locale* getBestMatch(const Locale& desiredLocale,
                               UErrorCode& errorCode) const U_LIFETIME_BOUND;

    const Locale* getBestMatch(Locale::Iterator& desiredLocales,
                               UErrorCode& errorCode) const U_LIFETIME_BOUND;

    const Locale* getBestMatchForListString(StringPiece desiredLocaleList,
                                            UErrorCode& errorCode) const U_LIFETIME_BOUND;

    Result getBestMatchResult(const Locale& desiredLocale U_LIFETIME_BOUND,
                              UErrorCode& errorCode) const U_LIFETIME_BOUND;

    Result getBestMatchResult(Locale::Iterator& desiredLocales,
                              UErrorCode& errorCode) const U_LIFETIME_BOUND;

    UBool isMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
 
#ifndef U_HIDE_INTERNAL_API
    double internalMatch(const Locale &desired, const Locale &supported, UErrorCode &errorCode) const;
#endif  // U_HIDE_INTERNAL_API
 
private:
    LocaleMatcher(const Builder &builder, UErrorCode &errorCode);
    LocaleMatcher(const LocaleMatcher &other) = delete;
    LocaleMatcher &operator=(const LocaleMatcher &other) = delete;
 
    int32_t putIfAbsent(const LSR &lsr, int32_t i, int32_t suppLength, UErrorCode &errorCode);
 
    std::optional<int32_t> getBestSuppIndex(LSR desiredLSR, LocaleLsrIterator *remainingIter, UErrorCode &errorCode) const;
 
    const LikelySubtags &likelySubtags;
    const LocaleDistance &localeDistance;
    int32_t thresholdDistance;
    int32_t demotionPerDesiredLocale;
    ULocMatchFavorSubtag favorSubtag;
    ULocMatchDirection direction;
 
    // These are in input order.
    const Locale ** supportedLocales;
    LSR *lsrs;
    int32_t supportedLocalesLength;
    // These are in preference order: 1. Default locale 2. paradigm locales 3. others.
    UHashtable *supportedLsrToIndex;  // Map<LSR, Integer>
    // Array versions of the supportedLsrToIndex keys and values.
    // The distance lookup loops over the supportedLSRs and returns the index of the best match.
    const LSR **supportedLSRs;
    int32_t *supportedIndexes;
    int32_t supportedLSRsLength;
    Locale *ownedDefaultLocale;
    const Locale *defaultLocale;
};
 
U_NAMESPACE_END
 
#endif  // U_SHOW_CPLUSPLUS_API
#endif  // __LOCALEMATCHER_H__