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 kcountrysubdivision.h <KCountrySubdivision>
18 *
19 * Information about an ISO 3166-2 country subdivision.
20 *
21 * @note This requires the [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes/)
22 * data files and translation catalogs to be available at runtime.
23 * @see KCountry for the data sources.
24 *
25 * @since 5.88
26 */
27class KI18NLOCALEDATA_EXPORT KCountrySubdivision
28{
29 Q_GADGET
30 Q_PROPERTY(QString code READ code)
31 Q_PROPERTY(QString name READ name)
32 Q_PROPERTY(KCountry country READ country)
33 Q_PROPERTY(KCountrySubdivision parent READ parent)
34 Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions)
35 Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList)
36
37public:
38 /** Creates an invalid/empty KCountrySubdivision instance.
39 * See the fromX() methods for creating a valid instance.
40 */
41 KCountrySubdivision();
42 KCountrySubdivision(const KCountrySubdivision &);
43 ~KCountrySubdivision();
44 KCountrySubdivision &operator=(const KCountrySubdivision &);
45
46 bool operator==(const KCountrySubdivision &other) const;
47 bool operator!=(const KCountrySubdivision &other) const;
48
49 /** Returns @c false if this is an empty/invalid/default constructed instance, @c true otherwise. */
50 bool isValid() const;
51
52 /** ISO 3166-2 country subdivision code. */
53 QString code() const;
54 /** Translated country subdivision name. */
55 QString name() const;
56 /** Country this subdivision belongs to. */
57 KCountry country() const;
58 /** Parent subdivision, if this is a subdivision of another subdivision.
59 * Returns an invalid element for top-level subdivisions.
60 */
61 KCountrySubdivision parent() const;
62
63 /** Timezones in use in this country subdivision. */
64 // for subdivisions we have to generate that by polygon intersections in QGIS -> POC
65 QList<const char *> timeZoneIds() const;
66 /** Subdivisions of this subdivision, if any.
67 * This is only relevant for countries with multiple ISO 3166-2 subdivision levels.
68 */
69 QList<KCountrySubdivision> subdivisions() const;
70
71 /** Create a KCountrySubdivision instance from an ISO 3166-2 code. */
72 static KCountrySubdivision fromCode(QStringView code);
73 /** Create a KCountrySubdivision instance from an ISO 3166-2 code. */
74 static KCountrySubdivision fromCode(const char *code);
75 /** Looks up the country subdivision at the given geographic coordinate.
76 * This can return an invalid object if the country subdivision could not be determined. This can happen in a number of cases:
77 * - on oceans
78 * - in polar regions
79 * - close to a land border
80 * - in disputed territories
81 * @note It is possible for KCountry::fromLocation() to return a valid result despite
82 * this method returning an invalid result.
83 */
84 static KCountrySubdivision fromLocation(float latitude, float longitude);
85
86private:
87 KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
88
89 friend class KCountry;
90 uint32_t d;
91};
92
93Q_DECLARE_TYPEINFO(KCountrySubdivision, Q_RELOCATABLE_TYPE);
94
95#endif // KCOUNTRYSUBDIVISION_H
96

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