## mateweather-location mateweather-location |

## Synopsis

                        MateWeatherLocation;
    enum                MateWeatherLocationLevel;
    MateWeatherLocation * mateweather_location_new_world    (gboolean use_regions);
    MateWeatherLocation * mateweather_location_ref          (MateWeatherLocation *loc);
    void                mateweather_location_unref          (MateWeatherLocation *loc);
    const char *        mateweather_location_get_name       (MateWeatherLocation *loc);
    const char *        mateweather_location_get_sort_name  (MateWeatherLocation *loc);
    MateWeatherLocationLevel mateweather_location_get_level (MateWeatherLocation *loc);
    MateWeatherLocation * mateweather_location_get_parent   (MateWeatherLocation *loc);
    MateWeatherLocation ** mateweather_location_get_children
                                                            (MateWeatherLocation *loc);
    void                mateweather_location_free_children  (MateWeatherLocation *loc,
                                                             MateWeatherLocation **children);
    gboolean            mateweather_location_has_coords     (MateWeatherLocation *loc);
    void                mateweather_location_get_coords     (MateWeatherLocation *loc,
                                                             double *latitude,
                                                             double *longitude);
    double              mateweather_location_get_distance   (MateWeatherLocation *loc,
                                                             MateWeatherLocation *loc2);
    const char *        mateweather_location_get_country    (MateWeatherLocation *loc);
    MateWeatherTimezone * mateweather_location_get_timezone (MateWeatherLocation *loc);
    MateWeatherTimezone ** mateweather_location_get_timezones
                                                            (MateWeatherLocation *loc);
    void                mateweather_location_free_timezones (MateWeatherLocation *loc,
                                                             MateWeatherTimezone **zones);
    const char *        mateweather_location_get_code       (MateWeatherLocation *loc);
    char *              mateweather_location_get_city_name  (MateWeatherLocation *loc);
    WeatherInfo *       mateweather_location_get_weather    (MateWeatherLocation *loc);

## Object Hierarchy

      GBoxed
       +----MateWeatherLocation

      GEnum
       +----MateWeatherLocationLevel

## Description

## Details

### MateWeatherLocation

    typedef struct _MateWeatherLocation MateWeatherLocation;

A MateWeatherLocation represents a "location" of some type known to libmateweather; anything from a single weather station to the entire world. See MateWeatherLocationLevel for information about how the hierarchy of locations works.

### enum MateWeatherLocationLevel

    typedef enum {
     /*< underscore_name=mateweather_location_level >*/
        MATEWEATHER_LOCATION_WORLD,
        MATEWEATHER_LOCATION_REGION,
        MATEWEATHER_LOCATION_COUNTRY,
        /* ADM1 = first-order administrative division = state/province, etc */
        MATEWEATHER_LOCATION_ADM1,
        /* ADM2 = second-order division = county, etc */
        MATEWEATHER_LOCATION_ADM2,
        MATEWEATHER_LOCATION_CITY,
        MATEWEATHER_LOCATION_WEATHER_STATION
    } MateWeatherLocationLevel;

The size/scope of a particular MateWeatherLocation.

Locations form a hierarchy, with a `MATEWEATHER_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.

`MATEWEATHER_LOCATION_WORLD` | A location representing the entire world.
`MATEWEATHER_LOCATION_REGION` | A location representing a continent or other top-level region.
`MATEWEATHER_LOCATION_COUNTRY` | A location representing a "country" (or other geographic unit that has an ISO-3166 country code)
`MATEWEATHER_LOCATION_ADM1` | A location representing a "first-level administrative division"; ie, a state, province, or similar division.
`MATEWEATHER_LOCATION_ADM2` | A location representing a subdivision of a `MATEWEATHER_LOCATION_ADM1` location. (Not currently used.)
`MATEWEATHER_LOCATION_CITY` | A location representing a city
`MATEWEATHER_LOCATION_WEATHER_STATION` | A location representing a weather station.

### mateweather_location_new_world ()

    MateWeatherLocation * mateweather_location_new_world    (gboolean use_regions);

Creates a new MateWeatherLocation of type `MATEWEATHER_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 `MATEWEATHER_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 `MATEWEATHER_LOCATION_COUNTRY` nodes.

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

### mateweather_location_ref ()

    MateWeatherLocation * mateweather_location_ref          (MateWeatherLocation *loc);

Adds 1 to `loc`'s reference count.

`loc` : | a MateWeatherLocation
Returns : | `loc`

### mateweather_location_unref ()

    void                mateweather_location_unref          (MateWeatherLocation *loc);

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

`loc` : | a MateWeatherLocation

### mateweather_location_get_name ()

    const char *        mateweather_location_get_name       (MateWeatherLocation *loc);

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

Note that `MATEWEATHER_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 MateWeatherLocation
Returns : | `loc`'s name

### mateweather_location_get_sort_name ()

    const char *        mateweather_location_get_sort_name  (MateWeatherLocation *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 MateWeatherLocation
Returns : | `loc`'s sort name

### mateweather_location_get_level ()

    MateWeatherLocationLevel mateweather_location_get_level (MateWeatherLocation *loc);

Gets `loc`'s level, from `MATEWEATHER_LOCATION_WORLD`, to `MATEWEATHER_LOCATION_WEATHER_STATION`.

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

### mateweather_location_get_parent ()

    MateWeatherLocation * mateweather_location_get_parent   (MateWeatherLocation *loc);

Gets `loc`'s parent location.

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

### mateweather_location_get_children ()

    MateWeatherLocation ** mateweather_location_get_children
                                                            (MateWeatherLocation *loc);

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

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

### mateweather_location_free_children ()

    void                mateweather_location_free_children  (MateWeatherLocation *loc,
                                                             MateWeatherLocation **children);

### Warning

`mateweather_location_free_children` is deprecated and should not be used in newly-written code. This is a no-op.

This is a no-op. Do not use it.

`loc` : | a MateWeatherLocation
`children` : | an array of `loc`'s children

### mateweather_location_has_coords ()

    gboolean            mateweather_location_has_coords     (MateWeatherLocation *loc);

Checks if `loc` has valid latitude and longitude.

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

### mateweather_location_get_coords ()

    void                mateweather_location_get_coords     (MateWeatherLocation *loc,
                                                             double *latitude,
                                                             double *longitude);

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

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

### mateweather_location_get_distance ()

    double              mateweather_location_get_distance   (MateWeatherLocation *loc,
                                                             MateWeatherLocation *loc2);

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

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

### mateweather_location_get_country ()

    const char *        mateweather_location_get_country    (MateWeatherLocation *loc);

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

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

### mateweather_location_get_timezone ()

    MateWeatherTimezone * mateweather_location_get_timezone (MateWeatherLocation *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 MateWeatherLocation
Returns : | `loc`'s timezone, or `NULL`. [transfer none][allow-none]

### mateweather_location_get_timezones ()

    MateWeatherTimezone ** mateweather_location_get_timezones
                                                            (MateWeatherLocation *loc);

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

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

### mateweather_location_free_timezones ()

    void                mateweather_location_free_timezones (MateWeatherLocation *loc,
                                                             MateWeatherTimezone **zones);

Frees the array of timezones returned by `mateweather_location_get_timezones()`.

`loc` : | a MateWeatherLocation
`zones` : | an array returned from `mateweather_location_get_timezones()`

### mateweather_location_get_code ()

    const char *        mateweather_location_get_code       (MateWeatherLocation *loc);

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

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

### mateweather_location_get_city_name ()

    char *              mateweather_location_get_city_name  (MateWeatherLocation *loc);

For a `MATEWEATHER_LOCATION_CITY` location, this is equivalent to `mateweather_location_get_name()`. For a `MATEWEATHER_LOCATION_WEATHER_STATION` location, it is equivalent to calling `mateweather_location_get_name()` on the location's parent. For other locations it will return `NULL`.

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

### mateweather_location_get_weather ()

    WeatherInfo *       mateweather_location_get_weather    (MateWeatherLocation *loc);

Creates a WeatherInfo corresponding to `loc`; you can use `weather_info_update()` to fill it in.

`loc` : | a `MateWeatherLocation`
Returns : | a WeatherInfo corresponding to `loc`. [transfer full]