KI18n

kcountry.h
1 /*
2  SPDX-FileCopyrightText: 2021 Volker Krause <[email protected]>
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 
17 class KCountry;
18 
19 namespace KTimeZone
20 {
21 KI18NLOCALEDATA_EXPORT KCountry country(const char *);
22 }
23 
24 /**
25  * @class KCountry kcountry.h <KCountry>
26  *
27  * Information about an ISO 3166-1 country.
28  *
29  * The information provided here are aggregated from the following sources:
30  * - [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes/)
31  * - [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder/)
32  * - [OSM](https://openstreetmap.org)
33  * - [CLDR](http://cldr.unicode.org/)
34  *
35  * @note This requires the iso-codes data files and translation catalogs to be available at runtime.
36  *
37  * @since 5.88
38  */
39 class KI18NLOCALEDATA_EXPORT KCountry
40 {
41  Q_GADGET
42  Q_PROPERTY(QString alpha2 READ alpha2)
43  Q_PROPERTY(QString alpha3 READ alpha3)
44  Q_PROPERTY(QString name READ name)
45  Q_PROPERTY(QString emojiFlag READ emojiFlag)
46  Q_PROPERTY(QString currencyCode READ currencyCode)
47  Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions)
48  Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList)
49 
50 public:
51  /** Creates an invalid/empty KCountry instance.
52  * See the fromX() methods for creating a valid instance.
53  */
54  KCountry();
55  KCountry(const KCountry &);
56  ~KCountry();
57  KCountry &operator=(const KCountry &);
58 
59  bool operator==(const KCountry &other) const;
60  bool operator!=(const KCountry &other) const;
61 
62  /** Returns @c false if this is an empty/invalid/default constructed instance, @c true otherwise. */
63  bool isValid() const;
64 
65  /** ISO 3166-1 alpha 2 country code. */
66  QString alpha2() const;
67  /** ISO 3166-1 alpha 3 country code. */
68  QString alpha3() const;
69  /** Translated country name. */
70  QString name() const;
71  /** Returns the Unicode flag emoji for this country. */
72  QString emojiFlag() const;
73  /** Returns the QLocale::Country value matching this country, or QLocale::AnyCountry if there is none. */
74  QLocale::Country country() const; // TODO better name?
75 
76  /** Timezones in use in this country. */
77  QList<const char *> timeZoneIds() const;
78  /** Currency used in this country as ISO 4217 code. */
79  QString currencyCode() const;
80  /** Highest level of ISO 3166-2 country subdivisions.
81  * If there is only one level of subdivisions this lists all of them,
82  * for countries with multiple levels, this only includes the top-level
83  * subdivisions (ie. those having no parent subdivision).
84  * @note: This can be empty.
85  */
86  QList<KCountrySubdivision> subdivisions() const;
87 
88  /** Create a KCountry instance from an ISO 3166-1 alpha 2 code. */
89  static KCountry fromAlpha2(QStringView alpha2Code);
90  /** Create a KCountry instance from an ISO 3166-1 alpha 2 code. */
91  static KCountry fromAlpha2(const char *alpha2Code);
92  /** Create a KCountry instance from an ISO 3166-1 alpha 3 code. */
93  static KCountry fromAlpha3(QStringView alpha3Code);
94  /** Create a KCountry instance from an ISO 3166-1 alpha 3 code. */
95  static KCountry fromAlpha3(const char *alpha3Code);
96  /** Looks up the country at the given geographic coordinate.
97  * This can return an invalid object if the country could not be determined. This can happen in a number of cases:
98  * - on oceans
99  * - in polar regions
100  * - close to a land border
101  * - in disputed territories
102  */
103  static KCountry fromLocation(float latitude, float longitude);
104  /** Returns a KCountry instance matching the given QLocale::Country code. */
105  static KCountry fromQLocale(QLocale::Country country);
106  /** Attempts to identify the country from the given name.
107  * The name can be in any language.
108  */
109  static KCountry fromName(QStringView name);
110 
111  /** List all countries. */
112  static QList<KCountry> allCountries();
113 
114 private:
115  QStringList timeZoneIdsStringList() const;
116 
117  friend class KCountrySubdivision;
118  friend KI18NLOCALEDATA_EXPORT KCountry KTimeZone::country(const char *);
119  uint16_t d;
120 };
121 
122 Q_DECLARE_METATYPE(KCountry)
123 Q_DECLARE_TYPEINFO(KCountry, Q_RELOCATABLE_TYPE);
124 
125 #endif // KCOUNTRY_H
KI18NLOCALEDATA_EXPORT KCountry country(const char *)
Returns the country a timezone is in.
Timezone localization methods.
Definition: kcountry.h:19
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Aug 15 2022 04:07:44 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.