KI18n

kcountry.h
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 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 */
39class 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
50public:
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
114private:
115 KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
116
117 friend class KCountrySubdivision;
118 friend KI18NLOCALEDATA_EXPORT KCountry KTimeZone::country(const char *);
119 uint16_t d;
120};
121
122Q_DECLARE_TYPEINFO(KCountry, Q_RELOCATABLE_TYPE);
123
124#endif // KCOUNTRY_H
Information about an ISO 3166-2 country subdivision.
Information about an ISO 3166-1 country.
Definition kcountry.h:40
Timezone localization methods.
Definition kcountry.h:20
KI18NLOCALEDATA_EXPORT KCountry country(const char *)
Returns the country a timezone is in.
Definition ktimezone.cpp:22
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:57:26 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.