Top | ![]() |
![]() |
![]() |
![]() |
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.
a MATEWEATHER_LOCATION_WORLD
location, or
NULL
if Locations.xml could not be found or could not be parsed.
MateWeatherLocation *
mateweather_location_ref (MateWeatherLocation *loc
);
Adds 1 to loc
's reference count.
void
mateweather_location_unref (MateWeatherLocation *loc
);
Subtracts 1 from loc
's reference count, and frees it if the
reference count reaches 0.
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?)
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.
MateWeatherLocationLevel
mateweather_location_get_level (MateWeatherLocation *loc
);
Gets loc
's level, from MATEWEATHER_LOCATION_WORLD
, to
MATEWEATHER_LOCATION_WEATHER_STATION
.
MateWeatherLocation *
mateweather_location_get_parent (MateWeatherLocation *loc
);
Gets loc
's parent location.
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
's
children. (May be empty, but will not be NULL
.).
[transfer none][array zero-terminated=1]
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.
gboolean
mateweather_location_has_coords (MateWeatherLocation *loc
);
Checks if loc
has valid latitude and longitude.
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.
double mateweather_location_get_distance (MateWeatherLocation *loc
,MateWeatherLocation *loc2
);
Determines the distance in kilometers between loc
and loc2
.
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)
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.
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.
an array
of timezones. May be empty but will not be NULL
.
[transfer full][array zero-terminated=1]
void mateweather_location_free_timezones (MateWeatherLocation *loc
,MateWeatherTimezone **zones
);
Frees the array of timezones returned by
mateweather_location_get_timezones()
.
const char *
mateweather_location_get_code (MateWeatherLocation *loc
);
Gets the METAR station code associated with a
MATEWEATHER_LOCATION_WEATHER_STATION
location.
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
.
WeatherInfo *
mateweather_location_get_weather (MateWeatherLocation *loc
);
Creates a WeatherInfo corresponding to loc
; you can use
weather_info_update()
to fill it in.
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.
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.
A location representing the entire world. |
||
A location representing a continent or other top-level region. |
||
A location representing a "country" (or other geographic unit that has an ISO-3166 country code) |
||
A location representing a "first-level administrative division"; ie, a state, province, or similar division. |
||
A location representing a subdivision of a
|
||
A location representing a city |
||
A location representing a weather station. |