mateweather-location

mateweather-location

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── MateWeatherLocation
    GEnum
    ╰── MateWeatherLocationLevel

Description

Functions

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.

Parameters

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.

Parameters

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.

Parameters


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?)

Parameters

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.

Parameters

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.

Parameters

Returns

loc 's level


mateweather_location_get_parent ()

MateWeatherLocation *
mateweather_location_get_parent (MateWeatherLocation *loc);

Gets loc 's parent location.

Parameters

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.

Parameters

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);

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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)

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

Returns

a WeatherInfo corresponding to loc .

[transfer full]

Types and Values

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

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.

Members

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.