diff options
-rw-r--r-- | navit/map.c | 9 | ||||
-rw-r--r-- | navit/mapset.c | 120 |
2 files changed, 118 insertions, 11 deletions
diff --git a/navit/map.c b/navit/map.c index f8253e97..d8a8e199 100644 --- a/navit/map.c +++ b/navit/map.c @@ -122,7 +122,7 @@ map_new(struct attr **attrs) * @param this_ The map the attribute should be read from * @param type The type of the attribute to be read * @param attr Pointer to an attrib-structure where the attribute should be written to - * @param iter Not used + * @param iter (NOT IMPLEMENTED) Used to iterate through all attributes of a type. Set this to NULL to get the first attribute, set this to an attr_iter to get the next attribute * @return True if the attribute type was found, false if not */ int @@ -140,7 +140,7 @@ map_get_attr(struct map *this_, enum attr_type type, struct attr *attr, struct a * * @param this_ The map to set the attribute of * @param attr The attribute to set - * @return True %FIXME why? + * @return True if the attr could be set, false otherwise */ int map_set_attr(struct map *this_, struct attr *attr) @@ -198,7 +198,7 @@ map_requires_conversion(struct map *this_) * * @param this_ The map the string to be converted is from * @param str The string to be converted - * @return The converted string + * @return The converted string. It has to be map_convert_free()d after use. */ char * map_convert_string(struct map *this_, char *str) @@ -371,6 +371,9 @@ struct map_search { * have a look into country.c for details. Because of that every map plugin has to accept a country item * to be passed as "superior item". * + * Note: If you change something here, please make shure to also update the documentation of mapset_search_new() + * in mapset.c! + * * @param m The map that should be searched * @param item Specifies a superior item to "search within" (see description) * @param search_attr Attribute specifying what to search for. See description. diff --git a/navit/mapset.c b/navit/mapset.c index 6f4a1694..5001ef2c 100644 --- a/navit/mapset.c +++ b/navit/mapset.c @@ -17,6 +17,15 @@ * Boston, MA 02110-1301, USA. */ +/** @file + * + * @brief Contains code used for loading more than one map + * + * The code in this file introduces "mapsets", which are collections of several maps. + * This enables navit to operate on more than one map at once. See map.c / map.h to learn + * how maps are handled. + */ + #include <string.h> #include <glib.h> #include <glib/gprintf.h> @@ -26,10 +35,20 @@ #include "projection.h" #include "map.h" +/** + * @brief A mapset + * + * This structure holds a complete mapset + */ struct mapset { - GList *maps; + GList *maps; /**< Linked list of all the maps in the mapset */ }; +/** + * @brief Creates a new, empty mapset + * + * @return The new mapset + */ struct mapset *mapset_new(void) { struct mapset *ms; @@ -39,6 +58,12 @@ struct mapset *mapset_new(void) return ms; } +/** + * @brief Adds a map to a mapset + * + * @param ms The mapset to add the map to + * @param m The map to be added + */ void mapset_add(struct mapset *ms, struct map *m) { ms->maps=g_list_append(ms->maps, m); @@ -51,15 +76,38 @@ static void mapset_maps_free(struct mapset *ms) } #endif +/** + * @brief Destroys a mapset. + * + * This destroys a mapset. Please note that it does not touch the contained maps + * in any way. + * + * @param ms The mapset to be destroyed + */ void mapset_destroy(struct mapset *ms) { g_free(ms); } +/** + * @brief Handle for a mapset in use + * + * This struct is used for a mapset that is in use. With this it is possible to iterate + * all maps in a mapset. + */ struct mapset_handle { - GList *l; + GList *l; /**< Pointer to the current (next) map */ }; +/** + * @brief Returns a new handle for a mapset + * + * This returns a new handle for an existing mapset. The new handle points to the first + * map in the set. + * + * @param ms The mapset to get a handle of + * @return The new mapset handle + */ struct mapset_handle * mapset_open(struct mapset *ms) { @@ -71,6 +119,16 @@ mapset_open(struct mapset *ms) return ret; } +/** + * @brief Gets the next map from a mapset handle + * + * If you set active to true, this function will not return any maps that + * have the attr_active attribute associated with them and set to false. + * + * @param msh The mapset handle to get the next map of + * @param active Set to true to only get active maps (See description) + * @return The next map + */ struct map * mapset_next(struct mapset_handle *msh, int active) { struct map *ret; @@ -90,20 +148,51 @@ struct map * mapset_next(struct mapset_handle *msh, int active) } } +/** + * @brief Closes a mapset handle after it is no longer used + * + * @param msh Mapset handle to be closed + */ void mapset_close(struct mapset_handle *msh) { g_free(msh); } +/** + * @brief Holds information about a search in a mapset + * + * This struct holds information about a search (e.g. for a street) in a mapset. + * + * @sa For a more detailed description see the documentation of mapset_search_new(). + */ struct mapset_search { - GList *map; - struct map_search *ms; - struct item *item; - struct attr *search_attr; - int partial; + GList *map; /**< The list of maps to be searched within */ + struct map_search *ms; /**< A map search struct for the map currently active */ + struct item *item; /**< "Superior" item. */ + struct attr *search_attr; /**< Attribute to be searched for. */ + int partial; /**< Indicates if one would like to have partial matches */ }; +/** + * @brief Starts a search on a mapset + * + * This function starts a search on a mapset. What attributes one can search for depends on the + * map plugin. See the description of map_search_new() in map.c for details. + * + * If you enable partial matches bear in mind that the search matches only the begin of the + * strings - a search for a street named "street" would match to "streetfoo", but not to + * "somestreet". Search is case insensitive. + * + * The item passed to this function specifies a "superior item" to "search within" - e.g. a town + * in which we want to search for a street, or a country in which to search for a town. + * + * @param ms The mapset that should be searched + * @param item Specifies a superior item to "search within" (see description) + * @param search_attr Attribute specifying what to search for. See description. + * @param partial Set this to true to also have partial matches. See description. + * @return A new mapset search struct for this search + */ struct mapset_search * mapset_search_new(struct mapset *ms, struct item *item, struct attr *search_attr, int partial) { @@ -118,13 +207,23 @@ mapset_search_new(struct mapset *ms, struct item *item, struct attr *search_attr return this; } +/** + * @brief Returns the next found item from a mapset search + * + * This function returns the next item from a mapset search or NULL if there are no more items found. + * It automatically iterates through all the maps in the mapset. Please note that maps which have the + * attr_active attribute associated with them and set to false are not searched. + * + * @param this The mapset search to return an item from + * @return The next found item or NULL if there are no more items found + */ struct item * mapset_search_get_item(struct mapset_search *this) { struct item *ret=NULL; struct attr active_attr; - while (!this->ms || !(ret=map_search_get_item(this->ms))) { + while (!this->ms || !(ret=map_search_get_item(this->ms))) { /* The current map has no more items to be returned */ if (this->search_attr->type >= attr_country_all && this->search_attr->type <= attr_country_name) break; for (;;) { @@ -144,6 +243,11 @@ mapset_search_get_item(struct mapset_search *this) return ret; } +/** + * @brief Destroys a mapset search + * + * @param this The mapset search to be destroyed + */ void mapset_search_destroy(struct mapset_search *this) { |