GWeatherLocation

## GWeatherLocation GWeatherLocation |

## Synopsis

    #include <libgweather/gweather.h>

                        GWeatherLocation;
    enum                GWeatherLocationLevel;
    GWeatherLocation *  gweather_location_new_world         (gboolean use_regions);
    GWeatherLocation *  gweather_location_ref               (GWeatherLocation *loc);
    void                gweather_location_unref             (GWeatherLocation *loc);

    GVariant *          gweather_location_serialize         (GWeatherLocation *loc);
    GWeatherLocation *  gweather_location_deserialize       (GWeatherLocation *world,
                                                             GVariant *serialized);
    gboolean            gweather_location_equal             (GWeatherLocation *one,
                                                             GWeatherLocation *two);
    GWeatherLocation *  gweather_location_find_by_station_code
                                                            (GWeatherLocation *world,
                                                             const gchar *station_code);

    GWeatherLocationLevel gweather_location_get_level       (GWeatherLocation *loc);
    GWeatherLocation *  gweather_location_get_parent        (GWeatherLocation *loc);
    GWeatherLocation ** gweather_location_get_children      (GWeatherLocation *loc);
    GWeatherLocation *  gweather_location_ref_world         (GWeatherLocation *loc);

    const char *        gweather_location_get_name          (GWeatherLocation *loc);
    const char *        gweather_location_get_sort_name     (GWeatherLocation *loc);
    gboolean            gweather_location_has_coords        (GWeatherLocation *loc);
    void                gweather_location_get_coords        (GWeatherLocation *loc,
                                                             double *latitude,
                                                             double *longitude);
    double              gweather_location_get_distance      (GWeatherLocation *loc,
                                                             GWeatherLocation *loc2);
    const char *        gweather_location_get_country       (GWeatherLocation *loc);
    GWeatherTimezone *  gweather_location_get_timezone      (GWeatherLocation *loc);
    GWeatherTimezone ** gweather_location_get_timezones     (GWeatherLocation *loc);
    const char *        gweather_location_get_code          (GWeatherLocation *loc);
    char *              gweather_location_get_city_name     (GWeatherLocation *loc);

## Object Hierarchy

      GBoxed
       +----GWeatherLocation

## Description

## Details

### GWeatherLocation

    typedef struct _GWeatherLocation GWeatherLocation;

### enum GWeatherLocationLevel

    typedef enum {
     /*< underscore_name=gweather_location_level >*/
        GWEATHER_LOCATION_WORLD,
        GWEATHER_LOCATION_REGION,
        GWEATHER_LOCATION_COUNTRY,
        /* ADM1 = first-order administrative division = state/province, etc */
        GWEATHER_LOCATION_ADM1,
        /* ADM2 = second-order division = county, etc */
        GWEATHER_LOCATION_ADM2,
        GWEATHER_LOCATION_CITY,
        GWEATHER_LOCATION_WEATHER_STATION,
        GWEATHER_LOCATION_DETACHED
    } GWeatherLocationLevel;

The size/scope of a particular GWeatherLocation.

Locations form a hierarchy, with a `GWEATHER_LOCATION_WORLD` location at the top, divided into regions or countries, and so on. Countries may or may not be divided into "adm1"s, and "adm1"s may or may not be divided into "adm2"s. A city will have at least one, and possibly several, weather stations inside it. Weather stations will never appear outside of cities.

Building a database with `gweather_location_new_world()` will never create detached instances, but deserializing might.

`GWEATHER_LOCATION_WORLD` | A location representing the entire world.
`GWEATHER_LOCATION_REGION` | A location representing a continent or other top-level region.
`GWEATHER_LOCATION_COUNTRY` | A location representing a "country" (or other geographic unit that has an ISO-3166 country code)
`GWEATHER_LOCATION_ADM1` | A location representing a "first-level administrative division"; ie, a state, province, or similar division.
`GWEATHER_LOCATION_ADM2` | A location representing a subdivision of a `GWEATHER_LOCATION_ADM1` location, or a direct subdivision of a country that is not represented in a GWeatherLocationEntry.
`GWEATHER_LOCATION_CITY` | A location representing a city
`GWEATHER_LOCATION_WEATHER_STATION` | A location representing a weather station.
`GWEATHER_LOCATION_DETACHED` | A location that is detached from the database, for example because it was loaded from external storage and could not be fully recovered. The parent of this location is the nearest weather station.

### gweather_location_new_world ()

    GWeatherLocation *  gweather_location_new_world         (gboolean use_regions);

Creates a new GWeatherLocation of type `GWEATHER_LOCATION_WORLD`, representing a hierarchy containing all of the locations from Locations.xml.

If `use_regions` is `TRUE`, the immediate children of the returned location will be `GWEATHER_LOCATION_REGION` nodes, representing the top-level "regions" of Locations.xml (the continents and a few other divisions), and the country-level nodes will be the children of the regions. If `use_regions` is `FALSE`, the regions will be skipped, and the children of the returned location will be the `GWEATHER_LOCATION_COUNTRY` nodes.

`use_regions` : | whether or not to divide the world into regions
Returns : | a `GWEATHER_LOCATION_WORLD` location, or `NULL` if Locations.xml could not be found or could not be parsed. [allow-none]

### gweather_location_ref ()

    GWeatherLocation *  gweather_location_ref               (GWeatherLocation *loc);

Adds 1 to `loc`'s reference count.

`loc` : | a GWeatherLocation
Returns : | `loc`

### gweather_location_unref ()

    void                gweather_location_unref             (GWeatherLocation *loc);

Subtracts 1 from `loc`'s reference count, and frees it if the reference count reaches 0.

`loc` : | a GWeatherLocation

### gweather_location_serialize ()

    GVariant *          gweather_location_serialize         (GWeatherLocation *loc);

`location` : | a GWeatherLocation
Returns : | . [transfer none]

### gweather_location_deserialize ()

    GWeatherLocation *  gweather_location_deserialize       (GWeatherLocation *world,
                                                             GVariant *serialized);

### gweather_location_equal ()

    gboolean            gweather_location_equal             (GWeatherLocation *one,
                                                             GWeatherLocation *two);

Compares two GWeatherLocation and sees if they represent the same place. It is only legal to call this for cities, weather stations or detached locations. Note that this function only checks for geographical characteristics, such as coordinates and METAR code. It is still possible that the two locations belong to different worlds (in which case care must be taken when passing them GWeatherLocationEntry and GWeatherInfo), or if one is them is detached it could have a custom name.

`one` : | a GWeatherLocation
`two` : | another GWeatherLocation
Returns : | `TRUE` if the two locations represent the same place as far as libgweather can tell, and `FALSE` otherwise.

### gweather_location_find_by_station_code ()

    GWeatherLocation *  gweather_location_find_by_station_code
                                                            (GWeatherLocation *world,
                                                             const gchar *station_code);

Retrieves the weather station identifier by `station_code`. Note that multiple instances of the same weather station can exist in the database, and this function will return any of them, so this not usually what you want.

See `gweather_location_deserialize()` to recover a stored GWeatherLocation.

`world` : | a GWeatherLocation at the world level
`station_code` : | a 4 letter METAR code
Returns : | a weather station level GWeatherLocation for `station_code`, or `NULL` if none exists in the database.

### gweather_location_get_level ()

    GWeatherLocationLevel gweather_location_get_level       (GWeatherLocation *loc);

Gets `loc`'s level, from `GWEATHER_LOCATION_WORLD`, to `GWEATHER_LOCATION_WEATHER_STATION`.

`loc` : | a GWeatherLocation
Returns : | `loc`'s level

### gweather_location_get_parent ()

    GWeatherLocation *  gweather_location_get_parent        (GWeatherLocation *loc);

Gets `loc`'s parent location.

`loc` : | a GWeatherLocation
Returns : | `loc`'s parent, or `NULL` if `loc` is a `GWEATHER_LOCATION_WORLD` node. [transfer none][allow-none]

### gweather_location_get_children ()

    GWeatherLocation ** gweather_location_get_children      (GWeatherLocation *loc);

Gets an array of `loc`'s children; this is owned by `loc` and will not remain valid if `loc` is freed.

`loc` : | a GWeatherLocation
Returns : | `loc`'s children. (May be empty, but will not be `NULL`.). [transfer none][array zero-terminated=1]

### gweather_location_ref_world ()

    GWeatherLocation *  gweather_location_ref_world         (GWeatherLocation *loc);

### gweather_location_get_name ()

    const char *        gweather_location_get_name          (GWeatherLocation *loc);

Gets `loc`'s name, localized into the current language.

Note that `GWEATHER_LOCATION_WEATHER_STATION` nodes are not localized, and so the name returned for those nodes will always be in English, and should therefore not be displayed to the user. (FIXME: should we just not return a name?)

`loc` : | a GWeatherLocation
Returns : | `loc`'s name

### gweather_location_get_sort_name ()

    const char *        gweather_location_get_sort_name     (GWeatherLocation *loc);

Gets `loc`'s "sort name", which is the name after having `g_utf8_normalize()` (with `G_NORMALIZE_ALL`) and `g_utf8_casefold()` called on it. You can use this to sort locations, or to comparing user input against a location name.

`loc` : | a GWeatherLocation
Returns : | `loc`'s sort name

### gweather_location_has_coords ()

    gboolean            gweather_location_has_coords        (GWeatherLocation *loc);

Checks if `loc` has valid latitude and longitude.

`loc` : | a GWeatherLocation
Returns : | `TRUE` if `loc` has valid latitude and longitude.

### gweather_location_get_coords ()

    void                gweather_location_get_coords        (GWeatherLocation *loc,
                                                             double *latitude,
                                                             double *longitude);

Gets `loc`'s coordinates; you must check `gweather_location_has_coords()` before calling this.

`loc` : | a GWeatherLocation
`latitude` : | on return will contain `loc`'s latitude. [out]
`longitude` : | on return will contain `loc`'s longitude. [out]

### gweather_location_get_distance ()

    double              gweather_location_get_distance      (GWeatherLocation *loc,
                                                             GWeatherLocation *loc2);

Determines the distance in kilometers between `loc` and `loc2`.

`loc` : | a GWeatherLocation
`loc2` : | a second GWeatherLocation
Returns : | the distance between `loc` and `loc2`.

### gweather_location_get_country ()

    const char *        gweather_location_get_country       (GWeatherLocation *loc);

Gets the ISO 3166 country code of `loc` (or `NULL` if `loc` is a region- or world-level location)

`loc` : | a GWeatherLocation
Returns : | `loc`'s country code (or `NULL` if `loc` is a region- or world-level location). [allow-none]

### gweather_location_get_timezone ()

    GWeatherTimezone *  gweather_location_get_timezone      (GWeatherLocation *loc);

Gets the timezone associated with `loc`, if known.

The timezone is owned either by `loc` or by one of its parents. FIXME.

`loc` : | a GWeatherLocation
Returns : | `loc`'s timezone, or `NULL`. [transfer none][allow-none]

### gweather_location_get_timezones ()

    GWeatherTimezone ** gweather_location_get_timezones     (GWeatherLocation *loc);

Gets an array of all timezones associated with any location under `loc`. You can use `gweather_location_free_timezones()` to free this array.

`loc` : | a GWeatherLocation
Returns : | an array of timezones. May be empty but will not be `NULL`. [transfer full][array zero-terminated=1]

### gweather_location_get_code ()

    const char *        gweather_location_get_code          (GWeatherLocation *loc);

Gets the METAR station code associated with a `GWEATHER_LOCATION_WEATHER_STATION` location.

`loc` : | a GWeatherLocation
Returns : | `loc`'s METAR station code, or `NULL`. [allow-none]

### gweather_location_get_city_name ()

    char *              gweather_location_get_city_name     (GWeatherLocation *loc);

For a `GWEATHER_LOCATION_CITY` or `GWEATHER_LOCATION_DETACHED` location, this is equivalent to `gweather_location_get_name()`. For a `GWEATHER_LOCATION_WEATHER_STATION` location, it is equivalent to calling `gweather_location_get_name()` on the location's parent. For other locations it will return `NULL`.

`loc` : | a GWeatherLocation
Returns : | (allow-none) `loc`'s city name, or `NULL`