File indexing completed on 2024-04-28 11:40:13
0001 /* 0002 SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KCOUNTRY_H 0008 #define KCOUNTRY_H 0009 0010 #include "ki18nlocaledata_export.h" 0011 0012 #include <QLocale> 0013 #include <QMetaType> 0014 0015 #include "kcountrysubdivision.h" 0016 0017 class KCountry; 0018 0019 namespace KTimeZone 0020 { 0021 KI18NLOCALEDATA_EXPORT KCountry country(const char *); 0022 } 0023 0024 /** 0025 * @class KCountry kcountry.h <KCountry> 0026 * 0027 * Information about an ISO 3166-1 country. 0028 * 0029 * The information provided here are aggregated from the following sources: 0030 * - [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes/) 0031 * - [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder/) 0032 * - [OSM](https://openstreetmap.org) 0033 * - [CLDR](http://cldr.unicode.org/) 0034 * 0035 * @note This requires the iso-codes data files and translation catalogs to be available at runtime. 0036 * 0037 * @since 5.88 0038 */ 0039 class KI18NLOCALEDATA_EXPORT KCountry 0040 { 0041 Q_GADGET 0042 Q_PROPERTY(QString alpha2 READ alpha2) 0043 Q_PROPERTY(QString alpha3 READ alpha3) 0044 Q_PROPERTY(QString name READ name) 0045 Q_PROPERTY(QString emojiFlag READ emojiFlag) 0046 Q_PROPERTY(QString currencyCode READ currencyCode) 0047 Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions) 0048 Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList) 0049 0050 public: 0051 /** Creates an invalid/empty KCountry instance. 0052 * See the fromX() methods for creating a valid instance. 0053 */ 0054 KCountry(); 0055 KCountry(const KCountry &); 0056 ~KCountry(); 0057 KCountry &operator=(const KCountry &); 0058 0059 bool operator==(const KCountry &other) const; 0060 bool operator!=(const KCountry &other) const; 0061 0062 /** Returns @c false if this is an empty/invalid/default constructed instance, @c true otherwise. */ 0063 bool isValid() const; 0064 0065 /** ISO 3166-1 alpha 2 country code. */ 0066 QString alpha2() const; 0067 /** ISO 3166-1 alpha 3 country code. */ 0068 QString alpha3() const; 0069 /** Translated country name. */ 0070 QString name() const; 0071 /** Returns the Unicode flag emoji for this country. */ 0072 QString emojiFlag() const; 0073 /** Returns the QLocale::Country value matching this country, or QLocale::AnyCountry if there is none. */ 0074 QLocale::Country country() const; // TODO better name? 0075 0076 /** Timezones in use in this country. */ 0077 QList<const char *> timeZoneIds() const; 0078 /** Currency used in this country as ISO 4217 code. */ 0079 QString currencyCode() const; 0080 /** Highest level of ISO 3166-2 country subdivisions. 0081 * If there is only one level of subdivisions this lists all of them, 0082 * for countries with multiple levels, this only includes the top-level 0083 * subdivisions (ie. those having no parent subdivision). 0084 * @note: This can be empty. 0085 */ 0086 QList<KCountrySubdivision> subdivisions() const; 0087 0088 /** Create a KCountry instance from an ISO 3166-1 alpha 2 code. */ 0089 static KCountry fromAlpha2(QStringView alpha2Code); 0090 /** Create a KCountry instance from an ISO 3166-1 alpha 2 code. */ 0091 static KCountry fromAlpha2(const char *alpha2Code); 0092 /** Create a KCountry instance from an ISO 3166-1 alpha 3 code. */ 0093 static KCountry fromAlpha3(QStringView alpha3Code); 0094 /** Create a KCountry instance from an ISO 3166-1 alpha 3 code. */ 0095 static KCountry fromAlpha3(const char *alpha3Code); 0096 /** Looks up the country at the given geographic coordinate. 0097 * This can return an invalid object if the country could not be determined. This can happen in a number of cases: 0098 * - on oceans 0099 * - in polar regions 0100 * - close to a land border 0101 * - in disputed territories 0102 */ 0103 static KCountry fromLocation(float latitude, float longitude); 0104 /** Returns a KCountry instance matching the given QLocale::Country code. */ 0105 static KCountry fromQLocale(QLocale::Country country); 0106 /** Attempts to identify the country from the given name. 0107 * The name can be in any language. 0108 */ 0109 static KCountry fromName(QStringView name); 0110 0111 /** List all countries. */ 0112 static QList<KCountry> allCountries(); 0113 0114 private: 0115 KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const; 0116 0117 friend class KCountrySubdivision; 0118 friend KI18NLOCALEDATA_EXPORT KCountry KTimeZone::country(const char *); 0119 uint16_t d; 0120 }; 0121 0122 Q_DECLARE_METATYPE(KCountry) 0123 Q_DECLARE_TYPEINFO(KCountry, Q_RELOCATABLE_TYPE); 0124 0125 #endif // KCOUNTRY_H