1/*
2 SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KCOUNTRY_H
8#define KCOUNTRY_H
9
10#include "ki18nlocaledata_export.h"
11
12#include <QLocale>
13#include <QMetaType>
14
15#include "kcountrysubdivision.h"
16
17class KCountry;
18
19namespace KTimeZone
20{
21KI18NLOCALEDATA_EXPORT KCountry country(const char *);
22}
23
24/*!
25 * \class KCountry
26 * \inmodule KI18nLocaleData
27 *
28 * \brief Information about an ISO 3166-1 country.
29 *
30 * The information provided here are aggregated from the following sources:
31 * \list
32 * \li \l {https://salsa.debian.org/iso-codes-team/iso-codes/} {iso-codes}
33 * \li \l {https://github.com/evansiroky/timezone-boundary-builder/} {timezone-boundary-builder}
34 * \li \l {https://openstreetmap.org} {OSM}
35 * \li \l {http://cldr.unicode.org/} {CLDR}
36 * \endlist
37 *
38 * \note This requires the iso-codes data files and translation catalogs to be available at runtime.
39 *
40 * \since 5.88
41 */
42class KI18NLOCALEDATA_EXPORT KCountry
43{
44 Q_GADGET
45
46 /*!
47 * \property KCountry::alpha2
48 */
49 Q_PROPERTY(QString alpha2 READ alpha2)
50
51 /*!
52 * \property KCountry::alpha3
53 */
54 Q_PROPERTY(QString alpha3 READ alpha3)
55
56 /*!
57 * \property KCountry::name
58 */
59 Q_PROPERTY(QString name READ name)
60
61 /*!
62 * \property KCountry::emojiFlag
63 */
64 Q_PROPERTY(QString emojiFlag READ emojiFlag)
65
66 /*!
67 * \property KCountry::currencyCode
68 */
69 Q_PROPERTY(QString currencyCode READ currencyCode)
70
71 /*!
72 * \property KCountry::subdivisions
73 */
74 Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions)
75
76 /*!
77 * \property KCountry::timeZoneIds
78 */
79 Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList)
80
81public:
82 /*!
83 * Creates an invalid/empty KCountry instance.
84 * See the fromX() methods for creating a valid instance.
85 */
86 KCountry();
87 KCountry(const KCountry &);
88 ~KCountry();
89 KCountry &operator=(const KCountry &);
90
91 /*!
92 *
93 */
94 bool operator==(const KCountry &other) const;
95 bool operator!=(const KCountry &other) const;
96
97 /*! Returns \c false if this is an empty/invalid/default constructed instance, \c true otherwise. */
98 bool isValid() const;
99
100 /*! ISO 3166-1 alpha 2 country code. */
101 QString alpha2() const;
102 /*! ISO 3166-1 alpha 3 country code. */
103 QString alpha3() const;
104 /*! Translated country name. */
105 QString name() const;
106 /*! Returns the Unicode flag emoji for this country. */
107 QString emojiFlag() const;
108 /*! Returns the QLocale::Country value matching this country, or QLocale::AnyCountry if there is none. */
109 QLocale::Country country() const; // TODO better name?
110
111 /*! Timezones in use in this country. */
112 QList<const char *> timeZoneIds() const;
113 /*! Currency used in this country as ISO 4217 code. */
114 QString currencyCode() const;
115 /*! Highest level of ISO 3166-2 country subdivisions.
116 * If there is only one level of subdivisions this lists all of them,
117 * for countries with multiple levels, this only includes the top-level
118 * subdivisions (ie. those having no parent subdivision).
119 * \note This can be empty.
120 */
121 QList<KCountrySubdivision> subdivisions() const;
122
123 /*! Create a KCountry instance from an ISO 3166-1 alpha 2 code. */
124 static KCountry fromAlpha2(QStringView alpha2Code);
125 /*! Create a KCountry instance from an ISO 3166-1 alpha 2 code. */
126 static KCountry fromAlpha2(const char *alpha2Code);
127 /*! Create a KCountry instance from an ISO 3166-1 alpha 3 code. */
128 static KCountry fromAlpha3(QStringView alpha3Code);
129 /*! Create a KCountry instance from an ISO 3166-1 alpha 3 code. */
130 static KCountry fromAlpha3(const char *alpha3Code);
131 /*! Looks up the country at the given geographic coordinate.
132 * This can return an invalid object if the country could not be determined. This can happen in a number of cases:
133 * \list
134 * \li on oceans
135 * \li in polar regions
136 * \li close to a land border
137 * \li in disputed territories
138 * \endlist
139 */
140 static KCountry fromLocation(float latitude, float longitude);
141 /*! Returns a KCountry instance matching the given QLocale::Country code. */
142 static KCountry fromQLocale(QLocale::Country country);
143 /*! Attempts to identify the country from the given name.
144 * The name can be in any language.
145 */
146 static KCountry fromName(QStringView name);
147
148 /*! List all countries. */
149 static QList<KCountry> allCountries();
150
151private:
152 KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
153
154 friend class KCountrySubdivision;
155 friend KI18NLOCALEDATA_EXPORT KCountry KTimeZone::country(const char *);
156 uint16_t d;
157};
158
159Q_DECLARE_TYPEINFO(KCountry, Q_RELOCATABLE_TYPE);
160
161#endif // KCOUNTRY_H
162

source code of ki18n/src/localedata/kcountry.h