gweather-location

gweather-location

Synopsis

                    GWeatherLocation;
enum                GWeatherLocationLevel;
GWeatherLocation *  gweather_location_new_world         (gboolean use_regions);
GWeatherLocation *  gweather_location_ref               (GWeatherLocation *loc);
void                gweather_location_unref             (GWeatherLocation *loc);
const char *        gweather_location_get_name          (GWeatherLocation *loc);
const char *        gweather_location_get_sort_name     (GWeatherLocation *loc);
GWeatherLocationLevel  gweather_location_get_level      (GWeatherLocation *loc);
GWeatherLocation *  gweather_location_get_parent        (GWeatherLocation *loc);
GWeatherLocation ** gweather_location_get_children      (GWeatherLocation *loc);
void                gweather_location_free_children     (GWeatherLocation *loc,
                                                         GWeatherLocation **children);
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);
void                gweather_location_free_timezones    (GWeatherLocation *loc,
                                                         GWeatherTimezone **zones);
const char *        gweather_location_get_code          (GWeatherLocation *loc);
char *              gweather_location_get_city_name     (GWeatherLocation *loc);
WeatherInfo *       gweather_location_get_weather       (GWeatherLocation *loc);

Description

Details

GWeatherLocation

typedef struct _GWeatherLocation GWeatherLocation;

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


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
} 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.

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. (Not currently used.)

GWEATHER_LOCATION_CITY

A location representing a city

GWEATHER_LOCATION_WEATHER_STATION

A location representing a 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 :

allow-none. 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_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_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 :

transfer none) (allow-none. 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 :

transfer none) (array zero-terminated=1. transfer none. array zero-terminated=1.

gweather_location_free_children ()

void                gweather_location_free_children     (GWeatherLocation *loc,
                                                         GWeatherLocation **children);

Warning

gweather_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 GWeatherLocation

children :

an array of loc's children

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 :

allow-none. 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 :

transfer none) (allow-none. 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 :

transfer full) (array zero-terminated=1. transfer full. array zero-terminated=1.

gweather_location_free_timezones ()

void                gweather_location_free_timezones    (GWeatherLocation *loc,
                                                         GWeatherTimezone **zones);

Frees the array of timezones returned by gweather_location_get_timezones().

loc :

a GWeatherLocation

zones :

an array returned from gweather_location_get_timezones()

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

gweather_location_get_weather ()

WeatherInfo *       gweather_location_get_weather       (GWeatherLocation *loc);

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

loc :

a GWeatherLocation

Returns :

transfer full. transfer full.