[libgweather] API break: replace gweather_location_new_world() with gweather_location_get_world()

[Giovanni Campagna <gcampagna src gnome org>]

commit d5332e605a297f4ec402ea323946193962a4ed33
Author: Giovanni Campagna <gcampagna src gnome org>
Date:   Sat Jun 15 15:23:20 2013 +0200

    API break: replace gweather_location_new_world() with gweather_location_get_world()
    
    The only parameter to it was deprecated, and the name was misleading,
    as it was not creating a new world location but always returning
    the same one. Also, the memory management was wrong in case the
    application freed the world location immediately.
    
    At the same time, let's remove some old cruft in GWeatherLocation.

 doc/libgweather-sections.txt    |    4 +--
 libgweather/gweather-location.c |   71 ++++++++-------------------------------
 libgweather/gweather-location.h |    8 +----
 libgweather/location-entry.c    |    8 ++---
 libgweather/test_locations.c    |    7 +---
 libgweather/timezone-menu.c     |   15 +++-----
 libgweather/weather.c           |   11 ++----
 7 files changed, 30 insertions(+), 94 deletions(-)
---
diff --git a/doc/libgweather-sections.txt b/doc/libgweather-sections.txt
index 19ded17..ca7c320 100644
--- a/doc/libgweather-sections.txt
+++ b/doc/libgweather-sections.txt
@@ -44,7 +44,7 @@ GWeatherLocationEntryPrivate
 <TITLE>GWeatherLocation</TITLE>
 GWeatherLocation
 GWeatherLocationLevel
-gweather_location_new_world
+gweather_location_get_world
 gweather_location_ref
 gweather_location_unref
 
@@ -58,7 +58,6 @@ gweather_location_find_by_station_code
 gweather_location_get_level
 gweather_location_get_parent
 gweather_location_get_children
-gweather_location_ref_world
 
 <SUBSECTION>
 gweather_location_get_name
@@ -73,7 +72,6 @@ gweather_location_get_code
 gweather_location_get_city_name
 
 <SUBSECTION Private>
-gweather_location_free_children
 gweather_location_free_timezones
 
 <SUBSECTION Standard>
diff --git a/libgweather/gweather-location.c b/libgweather/gweather-location.c
index cf69ab4..7bdec54 100644
--- a/libgweather/gweather-location.c
+++ b/libgweather/gweather-location.c
@@ -77,7 +77,7 @@
  * and possibly several, weather stations inside it. Weather stations
  * will never appear outside of cities.
  *
- * Building a database with gweather_location_new_world() will never
+ * Building a database with gweather_location_get_world() will never
  * create detached instances, but deserializing might.
  **/
 
@@ -298,42 +298,29 @@ error_out:
 static GWeatherLocation *global_world;
 
 /**
- * gweather_location_new_world:
- * @use_regions: whether or not to divide the world into regions (deprecated)
+ * gweather_location_get_world:
  *
- * Creates a new #GWeatherLocation of type %GWEATHER_LOCATION_WORLD,
+ * Obtains the shared #GWeatherLocation of type %GWEATHER_LOCATION_WORLD,
  * representing a hierarchy containing all of the locations from
  * Locations.xml.
  *
- * Starting from 3.10, multiple invocations to this function return the
- * same location.
- *
- * In the past, the @use_regions parameter could be used to control
- * if the immediate children were %GWEATHER_LOCATION_REGION or
- * %GWEATHER_LOCATION_COUNTRY nodes. Now it is deprecated and treated
- * always as %TRUE. A diagnostic message is printed if %FALSE is passed.
- *
- * Return value: (allow-none) (transfer full): a %GWEATHER_LOCATION_WORLD
+ * Return value: (allow-none) (transfer none): a %GWEATHER_LOCATION_WORLD
  * location, or %NULL if Locations.xml could not be found or could not be parsed.
+ * The return value is owned by libgweather and should not be modified or freed.
  **/
 GWeatherLocation *
-gweather_location_new_world (gboolean use_regions)
+gweather_location_get_world (void)
 {
     GWeatherParser *parser;
 
-    if (!use_regions)
-       g_message ("passing FALSE to gweather_location_new_world() is deprecated, ignoring");
-
-    if (global_world)
-       return gweather_location_ref (global_world);
-
-    parser = gweather_parser_new (TRUE);
-    if (!parser)
-       return NULL;
+    if (!global_world) {
+       parser = gweather_parser_new (TRUE);
+       if (!parser)
+           return NULL;
 
-    global_world = location_new_from_xml (parser, GWEATHER_LOCATION_WORLD, NULL);
+       global_world = location_new_from_xml (parser, GWEATHER_LOCATION_WORLD, NULL);
+    }
 
-    gweather_parser_free (parser);
     return global_world;
 }
 
@@ -371,6 +358,8 @@ gweather_location_unref (GWeatherLocation *loc)
     if (--loc->ref_count)
        return;
 
+    g_return_if_fail (loc->level != GWEATHER_LOCATION_WORLD);
+
     g_free (loc->name);
     g_free (loc->sort_name);
     g_free (loc->country_code);
@@ -396,9 +385,6 @@ gweather_location_unref (GWeatherLocation *loc)
     if (loc->metar_code_cache)
        g_hash_table_unref (loc->metar_code_cache);
 
-    if (loc->level == GWEATHER_LOCATION_WORLD)
-       global_world = NULL;
-
     g_slice_free (GWeatherLocation, loc);
 }
 
@@ -510,23 +496,6 @@ gweather_location_get_children (GWeatherLocation *loc)
        return &no_children;
 }
 
-
-/**
- * gweather_location_free_children:
- * @loc: a #GWeatherLocation
- * @children: an array of @loc's children
- *
- * This is a no-op. Do not use it.
- *
- * Deprecated: This is a no-op.
- **/
-void
-gweather_location_free_children (GWeatherLocation  *loc,
-                                GWeatherLocation **children)
-{
-    ;
-}
-
 /**
  * gweather_location_has_coords:
  * @loc: a #GWeatherLocation
@@ -828,18 +797,6 @@ gweather_location_find_by_station_code (GWeatherLocation *world,
     return l ? l->data : NULL;
 }
 
-GWeatherLocation *
-gweather_location_ref_world (GWeatherLocation *loc)
-{
-    while (loc &&
-          loc->level != GWEATHER_LOCATION_WORLD)
-       loc = loc->parent;
-
-    if (loc)
-       gweather_location_ref (loc);
-    return loc;
-}
-
 /**
  * gweather_location_equal:
  * @one: a #GWeatherLocation
diff --git a/libgweather/gweather-location.h b/libgweather/gweather-location.h
index 7efcd94..72dfac2 100644
--- a/libgweather/gweather-location.h
+++ b/libgweather/gweather-location.h
@@ -48,7 +48,7 @@ typedef enum { /*< underscore_name=gweather_location_level >*/
 GType gweather_location_get_type (void);
 #define GWEATHER_TYPE_LOCATION (gweather_location_get_type ())
 
-GWeatherLocation      *gweather_location_new_world      (gboolean           use_regions);
+GWeatherLocation      *gweather_location_get_world      (void);
 GWeatherLocation      *gweather_location_ref            (GWeatherLocation  *loc);
 void                   gweather_location_unref          (GWeatherLocation  *loc);
 
@@ -58,10 +58,6 @@ GWeatherLocationLevel  gweather_location_get_level      (GWeatherLocation  *loc)
 GWeatherLocation      *gweather_location_get_parent     (GWeatherLocation  *loc);
 
 GWeatherLocation     **gweather_location_get_children   (GWeatherLocation  *loc);
-#ifndef GWEATHER_DISABLE_DEPRECATED
-void                   gweather_location_free_children  (GWeatherLocation  *loc,
-                                                        GWeatherLocation **children);
-#endif
 
 gboolean               gweather_location_has_coords     (GWeatherLocation  *loc);
 void                   gweather_location_get_coords     (GWeatherLocation  *loc,
@@ -83,8 +79,6 @@ char                  *gweather_location_get_city_name  (GWeatherLocation  *loc)
 GWeatherLocation      *gweather_location_find_by_station_code (GWeatherLocation *world,
                                                               const gchar      *station_code);
 
-GWeatherLocation      *gweather_location_ref_world      (GWeatherLocation  *loc);
-
 gboolean               gweather_location_equal          (GWeatherLocation  *one,
                                                         GWeatherLocation  *two);
 
diff --git a/libgweather/location-entry.c b/libgweather/location-entry.c
index aa96da8..7fe58fc 100644
--- a/libgweather/location-entry.c
+++ b/libgweather/location-entry.c
@@ -547,8 +547,6 @@ fill_location_entry_model (GtkTreeStore *store, GWeatherLocation *loc,
     case GWEATHER_LOCATION_DETACHED:
        g_assert_not_reached ();
     }
-
-    gweather_location_free_children (loc, children);
 }
 
 static void
@@ -560,7 +558,7 @@ gweather_location_entry_build_model (GWeatherLocationEntry *entry,
     if (top)
        entry->priv->top = gweather_location_ref (top);
     else
-       entry->priv->top = gweather_location_new_world (TRUE);
+       entry->priv->top = gweather_location_ref (gweather_location_get_world ());
 
     store = gtk_tree_store_new (4, G_TYPE_STRING, GWEATHER_TYPE_LOCATION, G_TYPE_STRING, G_TYPE_STRING);
     fill_location_entry_model (store, entry->priv->top, NULL, NULL);
@@ -663,8 +661,8 @@ match_selected (GtkEntryCompletion *completion,
  *
  * Creates a new #GWeatherLocationEntry.
  *
- * @top will normally be a location returned from
- * gweather_location_new_world(), but you can create an entry that
+ * @top will normally be the location returned from
+ * gweather_location_get_world(), but you can create an entry that
  * only accepts a smaller set of locations if you want.
  *
  * Return value: the new #GWeatherLocationEntry
diff --git a/libgweather/test_locations.c b/libgweather/test_locations.c
index 842cb45..afeffb9 100644
--- a/libgweather/test_locations.c
+++ b/libgweather/test_locations.c
@@ -31,7 +31,6 @@ location_changed (GObject *object, GParamSpec *param, gpointer tzmenu)
 int
 main (int argc, char **argv)
 {
-    GWeatherLocation *loc;
     GtkWidget *window, *vbox, *entry;
     GtkWidget *combo;
     gtk_init (&argc, &argv);
@@ -45,13 +44,11 @@ main (int argc, char **argv)
     vbox = gtk_box_new (GTK_ORIENTATION_VERTICAL, 8);
     gtk_container_add (GTK_CONTAINER (window), vbox);
 
-    loc = gweather_location_new_world (FALSE);
-    entry = gweather_location_entry_new (loc);
+    entry = gweather_location_entry_new (NULL);
     gtk_widget_set_size_request (entry, 400, -1);
     gtk_box_pack_start (GTK_BOX (vbox), entry, FALSE, TRUE, 0);
 
-    combo = gweather_timezone_menu_new (loc);
-    gweather_location_unref (loc);
+    combo = gweather_timezone_menu_new (NULL);
     gtk_box_pack_start (GTK_BOX (vbox), combo, FALSE, TRUE, 0);
 
     g_signal_connect (entry, "notify::location",
diff --git a/libgweather/timezone-menu.c b/libgweather/timezone-menu.c
index f4592fb..87b4f51 100644
--- a/libgweather/timezone-menu.c
+++ b/libgweather/timezone-menu.c
@@ -268,7 +268,6 @@ gweather_timezone_model_new (GWeatherLocation *top)
     GtkTreeIter iter;
     char *unknown;
     GWeatherTimezone *utc;
-    GWeatherLocation *world;
 
     store = gtk_tree_store_new (2, G_TYPE_STRING, GWEATHER_TYPE_TIMEZONE);
     model = GTK_TREE_MODEL (store);
@@ -291,14 +290,10 @@ gweather_timezone_model_new (GWeatherLocation *top)
 
     g_free (unknown);
 
-    if (top)
-       world = gweather_location_ref (top);
-    else
-       world = gweather_location_new_world (TRUE);
-
-    insert_locations (store, world);
+    if (!top)
+       top = gweather_location_get_world ();
 
-    gweather_location_unref (world);
+    insert_locations (store, top);
 
     return model;
 }
@@ -334,8 +329,8 @@ is_sensitive (GtkCellLayout *cell_layout, GtkCellRenderer *cell,
  *
  * Creates a new #GWeatherTimezoneMenu.
  *
- * @top will normally be a location returned from
- * gweather_location_new_world(), but you can create a menu that
+ * @top will normally be the location returned from
+ * gweather_location_get_world(), but you can create a menu that
  * contains the timezones from a smaller set of locations if you want.
  *
  * Return value: the new #GWeatherTimezoneMenu
diff --git a/libgweather/weather.c b/libgweather/weather.c
index 9dad494..e4aedf2 100644
--- a/libgweather/weather.c
+++ b/libgweather/weather.c
@@ -2015,16 +2015,12 @@ gweather_info_set_location_internal (GWeatherInfo     *info,
        gweather_location_unref (priv->glocation);
     _weather_location_free (&priv->location);
 
-    if (!priv->world && location)
-       priv->world = gweather_location_ref_world (location);
-
-    if (!priv->world)
-       priv->world = gweather_location_new_world (TRUE);
-
     priv->glocation = location;
+
     if (priv->glocation) {
        gweather_location_ref (location);
     } else {
+       GWeatherLocation *world;
        GVariant *default_loc = g_settings_get_value (priv->settings, DEFAULT_LOCATION);
        const gchar *station_code;
 
@@ -2033,7 +2029,8 @@ gweather_info_set_location_internal (GWeatherInfo     *info,
        if (strcmp(name, "") == 0)
            name = NULL;
 
-       priv->glocation = gweather_location_find_by_station_code (priv->world, station_code);
+       world = gweather_location_get_world ();
+       priv->glocation = gweather_location_find_by_station_code (world, station_code);
     }
 
     _gweather_location_update_weather_location (priv->glocation,