1/*
2 SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KCOUNTRYSUBDIVISION_H
8#define KCOUNTRYSUBDIVISION_H
9
10#include "ki18nlocaledata_export.h"
11
12#include <QMetaType>
13
14class KCountry;
15
16/*!
17 * \class KCountrySubdivision
18 * \inmodule KI18nLocaleData
19 *
20 * \brief Information about an ISO 3166-2 country subdivision.
21 *
22 * \note This requires the [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes/)
23 * data files and translation catalogs to be available at runtime.
24 *
25 * See KCountry for the data sources.
26 *
27 * \since 5.88
28 */
29class KI18NLOCALEDATA_EXPORT KCountrySubdivision
30{
31 Q_GADGET
32
33 /*!
34 * \property KCountrySubdivision::code
35 */
36 Q_PROPERTY(QString code READ code)
37
38 /*!
39 * \property KCountrySubdivision::name
40 */
41 Q_PROPERTY(QString name READ name)
42
43 /*!
44 * \property KCountrySubdivision::country
45 */
46 Q_PROPERTY(KCountry country READ country)
47
48 /*!
49 * \property KCountrySubdivision::parent
50 */
51 Q_PROPERTY(KCountrySubdivision parent READ parent)
52
53 /*!
54 * \property KCountrySubdivision::subdivisions
55 */
56 Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions)
57
58 /*!
59 * \property KCountrySubdivision::timeZoneIds
60 */
61 Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList)
62
63public:
64 /*!
65 * Creates an invalid/empty KCountrySubdivision instance.
66 * See the fromX() methods for creating a valid instance.
67 */
68 KCountrySubdivision();
69 KCountrySubdivision(const KCountrySubdivision &);
70 ~KCountrySubdivision();
71 KCountrySubdivision &operator=(const KCountrySubdivision &);
72
73 /*!
74 *
75 */
76 bool operator==(const KCountrySubdivision &other) const;
77 bool operator!=(const KCountrySubdivision &other) const;
78
79 /*! Returns \c false if this is an empty/invalid/default constructed instance, \c true otherwise. */
80 bool isValid() const;
81
82 /*! ISO 3166-2 country subdivision code. */
83 QString code() const;
84 /*! Translated country subdivision name. */
85 QString name() const;
86 /*! Country this subdivision belongs to. */
87 KCountry country() const;
88 /*! Parent subdivision, if this is a subdivision of another subdivision.
89 * Returns an invalid element for top-level subdivisions.
90 */
91 KCountrySubdivision parent() const;
92
93 // for subdivisions we have to generate that by polygon intersections in QGIS -> POC
94 /*! Timezones in use in this country subdivision. */
95 QList<const char *> timeZoneIds() const;
96 /*! Subdivisions of this subdivision, if any.
97 * This is only relevant for countries with multiple ISO 3166-2 subdivision levels.
98 */
99 QList<KCountrySubdivision> subdivisions() const;
100
101 /*! Create a KCountrySubdivision instance from an ISO 3166-2 code. */
102 static KCountrySubdivision fromCode(QStringView code);
103 /*! Create a KCountrySubdivision instance from an ISO 3166-2 code. */
104 static KCountrySubdivision fromCode(const char *code);
105 /*! Looks up the country subdivision at the given geographic coordinate.
106 * This can return an invalid object if the country subdivision could not be determined. This can happen in a number of cases:
107 * \list
108 * \li on oceans
109 * \li in polar regions
110 * \li close to a land border
111 * \li in disputed territories
112 * \endlist
113 * \note It is possible for KCountry::fromLocation() to return a valid result despite
114 * this method returning an invalid result.
115 */
116 static KCountrySubdivision fromLocation(float latitude, float longitude);
117
118private:
119 KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
120
121 friend class KCountry;
122 uint32_t d;
123};
124
125Q_DECLARE_TYPEINFO(KCountrySubdivision, Q_RELOCATABLE_TYPE);
126
127#endif // KCOUNTRYSUBDIVISION_H
128

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