KI18n

kcountrysubdivision.h
1 /*
2  SPDX-FileCopyrightText: 2021 Volker Krause <[email protected]>
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 
14 class 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  */
27 class 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 
37 public:
38  /** Creates an invalid/empty KCountrySubdivision instance.
39  * See the fromX() methods for creating a valid instance.
40  */
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 
86 private:
87  KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
88 
89  friend class KCountry;
90  uint32_t d;
91 };
92 
93 Q_DECLARE_METATYPE(KCountrySubdivision)
94 Q_DECLARE_TYPEINFO(KCountrySubdivision, Q_RELOCATABLE_TYPE);
95 
96 #endif // KCOUNTRYSUBDIVISION_H
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 04:09:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.