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

 /*
     SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KCOUNTRY_H
 #define KCOUNTRY_H
 
 #include "ki18nlocaledata_export.h"
 
 #include <QLocale>
 #include <QMetaType>
 
 #include "kcountrysubdivision.h"
 
 class KCountry;
 
 namespace KTimeZone
 {
 KI18NLOCALEDATA_EXPORT KCountry country(const char *);
 }
 
 /**
  *  @class KCountry kcountry.h <KCountry>
  *
  *  Information about an ISO 3166-1 country.
  *
  *  The information provided here are aggregated from the following sources:
  *  - [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes/)
  *  - [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder/)
  *  - [OSM](https://openstreetmap.org)
  *  - [CLDR](http://cldr.unicode.org/)
  *
  *  @note This requires the iso-codes data files and translation catalogs to be available at runtime.
  *
  *  @since 5.88
  */
 class KI18NLOCALEDATA_EXPORT KCountry
 {
     Q_GADGET
     Q_PROPERTY(QString alpha2 READ alpha2)
     Q_PROPERTY(QString alpha3 READ alpha3)
     Q_PROPERTY(QString name READ name)
     Q_PROPERTY(QString emojiFlag READ emojiFlag)
     Q_PROPERTY(QString currencyCode READ currencyCode)
     Q_PROPERTY(QList<KCountrySubdivision> subdivisions READ subdivisions)
     Q_PROPERTY(QStringList timeZoneIds READ timeZoneIdsStringList)
 
 public:
     /** Creates an invalid/empty KCountry instance.
      *  See the fromX() methods for creating a valid instance.
      */
     KCountry();
     KCountry(const KCountry &);
     ~KCountry();
     KCountry &operator=(const KCountry &);
 
     bool operator==(const KCountry &other) const;
     bool operator!=(const KCountry &other) const;
 
     /** Returns @c false if this is an empty/invalid/default constructed instance, @c true otherwise. */
     bool isValid() const;
 
     /** ISO 3166-1 alpha 2 country code. */
     QString alpha2() const;
     /** ISO 3166-1 alpha 3 country code. */
     QString alpha3() const;
     /** Translated country name. */
     QString name() const;
     /** Returns the Unicode flag emoji for this country. */
     QString emojiFlag() const;
     /** Returns the QLocale::Country value matching this country, or QLocale::AnyCountry if there is none. */
     QLocale::Country country() const; // TODO better name?
 
     /** Timezones in use in this country. */
     QList<const char *> timeZoneIds() const;
     /** Currency used in this country as ISO 4217 code. */
     QString currencyCode() const;
     /** Highest level of ISO 3166-2 country subdivisions.
      *  If there is only one level of subdivisions this lists all of them,
      *  for countries with multiple levels, this only includes the top-level
      *  subdivisions (ie. those having no parent subdivision).
      *  @note: This can be empty.
      */
     QList<KCountrySubdivision> subdivisions() const;
 
     /** Create a KCountry instance from an ISO 3166-1 alpha 2 code. */
     static KCountry fromAlpha2(QStringView alpha2Code);
     /** Create a KCountry instance from an ISO 3166-1 alpha 2 code. */
     static KCountry fromAlpha2(const char *alpha2Code);
     /** Create a KCountry instance from an ISO 3166-1 alpha 3 code. */
     static KCountry fromAlpha3(QStringView alpha3Code);
     /** Create a KCountry instance from an ISO 3166-1 alpha 3 code. */
     static KCountry fromAlpha3(const char *alpha3Code);
     /** Looks up the country at the given geographic coordinate.
      *  This can return an invalid object if the country could not be determined. This can happen in a number of cases:
      *  - on oceans
      *  - in polar regions
      *  - close to a land border
      *  - in disputed territories
      */
     static KCountry fromLocation(float latitude, float longitude);
     /** Returns a KCountry instance matching the given QLocale::Country code. */
     static KCountry fromQLocale(QLocale::Country country);
     /** Attempts to identify the country from the given name.
      *  The name can be in any language.
      */
     static KCountry fromName(QStringView name);
 
     /** List all countries. */
     static QList<KCountry> allCountries();
 
 private:
     KI18NLOCALEDATA_NO_EXPORT QStringList timeZoneIdsStringList() const;
 
     friend class KCountrySubdivision;
     friend KI18NLOCALEDATA_EXPORT KCountry KTimeZone::country(const char *);
     uint16_t d;
 };
 
 Q_DECLARE_TYPEINFO(KCountry, Q_RELOCATABLE_TYPE);
 
 #endif // KCOUNTRY_H