[libgweather] Fix gweather_location_find_nearest_city

[Giovanni Campagna <gcampagna src gnome org>]

commit f5ce8cab9e4a041cbb5e3d54230ac7ccbdb28734
Author: Giovanni Campagna <gcampagna src gnome org>
Date:   Fri Oct 25 17:02:35 2013 +0200

    Fix gweather_location_find_nearest_city
    
    Add a location parameter to limit the search, and use the standard
    lat/lon abbreviations. Also add warnings to the documentations
    for the risks associated with this function and geolocation.

 libgweather/gweather-location.c |   31 ++++++++++++++++++++++---------
 libgweather/gweather-location.h |    4 +++-
 2 files changed, 25 insertions(+), 10 deletions(-)
---
diff --git a/libgweather/gweather-location.c b/libgweather/gweather-location.c
index 0dddbf5..ca840f1 100644
--- a/libgweather/gweather-location.c
+++ b/libgweather/gweather-location.c
@@ -554,33 +554,46 @@ find_nearest_city (GWeatherLocation *location,
 
 /**
  * gweather_location_find_nearest_city:
- * @loc: The parent location, which will be searched recursively
+ * @loc: (allow-none): The parent location, which will be searched recursively
  * @lat: Latitude, in degrees
- * @long_: Longitude, in degrees
+ * @lon: Longitude, in degrees
  *
  * Finds the nearest city to the passed latitude and
- * longitude.
+ * longitude, among the descendants of @loc.
  *
- * Returns: (transfer full): the closest city
+ * @loc must be at most a %GWEATHER_LOCATION_LEVEL_ADM2 location.
+ * This restriction may be lifted in a future version.
+ *
+ * Note that this function does not check if (@lat, @lon) fall inside
+ * @loc, or are in the same region and timezone as the return value.
+ *
+ * Returns: (transfer full): the city closest to (@lat, @lon), in the
+ *          region or administrative district of @loc.
  */
 GWeatherLocation *
-gweather_location_find_nearest_city (double lat, double long_)
+gweather_location_find_nearest_city (GWeatherLocation *loc,
+                                    double            lat,
+                                    double            lon)
 {
    /* The data set really isn't too big. Don't concern ourselves
      * with a proper nearest neighbors search. Instead, just do
      * an O(n) search. */
-    GWeatherLocation *world = gweather_location_get_world ();
     struct FindNearestCityData data;
 
+    g_return_val_if_fail (loc == NULL || loc->level < GWEATHER_LOCATION_CITY, NULL);
+
+    if (loc == NULL)
+       loc = gweather_location_get_world ();
+
     lat = lat * M_PI / 180.0;
-    long_ = long_ * M_PI / 180.0;
+    lon = lon * M_PI / 180.0;
 
     data.latitude = lat;
-    data.longitude = long_;
+    data.longitude = lon;
     data.location = NULL;
     data.distance = 0.0;
 
-    foreach_cities (world, (GFunc) find_nearest_city, &data);
+    foreach_cities (loc, (GFunc) find_nearest_city, &data);
 
     return gweather_location_ref (data.location);
 }
diff --git a/libgweather/gweather-location.h b/libgweather/gweather-location.h
index 5a64f06..c97566f 100644
--- a/libgweather/gweather-location.h
+++ b/libgweather/gweather-location.h
@@ -69,7 +69,9 @@ void                   gweather_location_get_coords     (GWeatherLocation  *loc,
                                                         double            *longitude);
 double                 gweather_location_get_distance   (GWeatherLocation  *loc,
                                                         GWeatherLocation  *loc2);
-GWeatherLocation      *gweather_location_find_nearest_city (double lat, double long_);
+GWeatherLocation      *gweather_location_find_nearest_city (GWeatherLocation *loc,
+                                                           double            lat,
+                                                           double            lon);
 
 const char            *gweather_location_get_country    (GWeatherLocation  *loc);