File indexing completed on 2024-04-21 03:54:30 

0001 /*
0002     SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef KCOUNTRYSUBDIVISION_H
0008 #define KCOUNTRYSUBDIVISION_H
0009 
0010 #include "ki18nlocaledata_export.h"
0011 
0012 #include <QMetaType>
0013 
0014 class KCountry;
0015 
0016 /**
0017  *  @class KCountrySubdivision kcountrysubdivision.h <KCountrySubdivision>
0018  *
0019  *  Information about an ISO 3166-2 country subdivision.
0020  *
0021  *  @note This requires the [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes/)
0022  *  data files and translation catalogs to be available at runtime.
0023  *  @see KCountry for the data sources.
0024  *
0025  *  @since 5.88
0026  */
0027 class KI18NLOCALEDATA_EXPORT KCountrySubdivision
0028 {
0029     Q_GADGET
0030     Q_PROPERTY(QString code READ code)
0031     Q_PROPERTY(QString name READ name)
0032     Q_PROPERTY(KCountry country READ country)
0033     Q_PROPERTY(KCountrySubdivision parent READ parent)
0034     Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions)
0035     Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList)
0036 
0037 public:
0038     /** Creates an invalid/empty KCountrySubdivision instance.
0039      *  See the fromX() methods for creating a valid instance.
0040      */
0041     KCountrySubdivision();
0042     KCountrySubdivision(const KCountrySubdivision &);
0043     ~KCountrySubdivision();
0044     KCountrySubdivision &operator=(const KCountrySubdivision &);
0045 
0046     bool operator==(const KCountrySubdivision &other) const;
0047     bool operator!=(const KCountrySubdivision &other) const;
0048 
0049     /** Returns @c false if this is an empty/invalid/default constructed instance, @c true otherwise. */
0050     bool isValid() const;
0051 
0052     /** ISO 3166-2 country subdivision code. */
0053     QString code() const;
0054     /** Translated country subdivision name. */
0055     QString name() const;
0056     /** Country this subdivision belongs to. */
0057     KCountry country() const;
0058     /** Parent subdivision, if this is a subdivision of another subdivision.
0059      * Returns an invalid element for top-level subdivisions.
0060      */
0061     KCountrySubdivision parent() const;
0062 
0063     /** Timezones in use in this country subdivision. */
0064     // for subdivisions we have to generate that by polygon intersections in QGIS -> POC
0065     QList<const char *> timeZoneIds() const;
0066     /** Subdivisions of this subdivision, if any.
0067      *  This is only relevant for countries with multiple ISO 3166-2 subdivision levels.
0068      */
0069     QList<KCountrySubdivision> subdivisions() const;
0070 
0071     /** Create a KCountrySubdivision instance from an ISO 3166-2 code. */
0072     static KCountrySubdivision fromCode(QStringView code);
0073     /** Create a KCountrySubdivision instance from an ISO 3166-2 code. */
0074     static KCountrySubdivision fromCode(const char *code);
0075     /** Looks up the country subdivision at the given geographic coordinate.
0076      *  This can return an invalid object if the country subdivision could not be determined. This can happen in a number of cases:
0077      *  - on oceans
0078      *  - in polar regions
0079      *  - close to a land border
0080      *  - in disputed territories
0081      *  @note It is possible for KCountry::fromLocation() to return a valid result despite
0082      *  this method returning an invalid result.
0083      */
0084     static KCountrySubdivision fromLocation(float latitude, float longitude);
0085 
0086 private:
0087     KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
0088 
0089     friend class KCountry;
0090     uint32_t d;
0091 };
0092 
0093 Q_DECLARE_TYPEINFO(KCountrySubdivision, Q_RELOCATABLE_TYPE);
0094 
0095 #endif // KCOUNTRYSUBDIVISION_H