diff --git a/src/mapping.c b/src/mapping.c index 0291cf97e2942a64f9c8495859baf6bf826725b8..8cc04b99d104c9abab2600f221d01fd126a3fe7c 100644 --- a/src/mapping.c +++ b/src/mapping.c @@ -2,7 +2,7 @@ || This file is part of Pike. For copyright information see COPYRIGHT. || Pike is distributed under GPL, LGPL and MPL. See the file COPYING || for more information. -|| $Id: mapping.c,v 1.184 2005/09/10 02:15:45 grendel Exp $ +|| $Id: mapping.c,v 1.185 2005/09/11 00:40:10 grendel Exp $ */ #include "global.h" @@ -647,15 +647,6 @@ PMOD_EXPORT void mapping_set_flags(struct mapping *m, int flags) md->flags = flags; } - -/** This function inserts key:val into the mapping m. - * Same as doing m[key]=val; in pike. - * - * @param overwrite how to deal with existing values@n - * @b 0: Do not replace the value if the entry exists.@n - * @b 1: Replace the value if the entry exists.@n - * @b 2: Replace both the index and the value if the entry exists. - */ PMOD_EXPORT void low_mapping_insert(struct mapping *m, const struct svalue *key, const struct svalue *val, diff --git a/src/mapping.h b/src/mapping.h index cebfa9fc69a3cffd81445b2b07445edfd5b8d3ed..4e0867278c57e1773cbee4e0c1c629c2ffc45cab 100644 --- a/src/mapping.h +++ b/src/mapping.h @@ -2,7 +2,7 @@ || This file is part of Pike. For copyright information see COPYRIGHT. || Pike is distributed under GPL, LGPL and MPL. See the file COPYING || for more information. -|| $Id: mapping.h,v 1.61 2005/09/10 02:15:45 grendel Exp $ +|| $Id: mapping.h,v 1.62 2005/09/11 00:40:10 grendel Exp $ */ #ifndef MAPPING_H @@ -160,6 +160,15 @@ PMOD_EXPORT void do_free_mapping(struct mapping *m); struct mapping_data *copy_mapping_data(struct mapping_data *md); PMOD_EXPORT void mapping_fix_type_field(struct mapping *m); PMOD_EXPORT void mapping_set_flags(struct mapping *m, int flags); + +/** This function inserts key:val into the mapping m. + * Same as doing m[key]=val; in pike. + * + * @param overwrite how to deal with existing values@n + * @b 0: Do not replace the value if the entry exists.@n + * @b 1: Replace the value if the entry exists.@n + * @b 2: Replace both the index and the value if the entry exists. + */ PMOD_EXPORT void low_mapping_insert(struct mapping *m, const struct svalue *key, const struct svalue *val, @@ -181,26 +190,143 @@ PMOD_EXPORT void mapping_insert(struct mapping *m, PMOD_EXPORT union anything *mapping_get_item_ptr(struct mapping *m, struct svalue *key, TYPE_T t); + +/** Deletes the specified entry from the indicated mapping and frees + * the memory associated with it unless the @b to parameter is not + * NULL, in which case the deleted item's value is assigned to the + * @b to @ref svalue. + * + * @param m mapping containing the entry to delete + * @param key the key which indexes the entry to delete + * @param to if not NULL will contain the deleted item's value + */ PMOD_EXPORT void map_delete_no_free(struct mapping *m, struct svalue *key, struct svalue *to); PMOD_EXPORT void check_mapping_for_destruct(struct mapping *m); + +/** Look up the specified key in the indicated mapping and return + * the corresponding @ref svalue representing the value of the + * entry. + * + * @param m mapping to check for the key presence + * @param key key to look up in the mapping + * @return an svalue representing the looked up entry's value or + * NULL if the key was not found in the mapping. + * @see low_mapping_string_lookup + * @see simple_mapping_string_lookup + */ PMOD_EXPORT struct svalue *low_mapping_lookup(struct mapping *m, const struct svalue *key); + +/** Look up an entry in the indicated mapping indexed by the passed @b Pike + * string. It is a shortcut for the common case when the mapping is indexed + * on Pike strings instead of using an @ref svalue and the @ref low_mapping_lookup + * function. + * + * @param m mapping to check for the key presence + * @param p a Pike string to use as the lookup key + * @return an svalue representing the looked up entry's value or NULL of no such + * item was found. + * @see low_mapping_lookup + * @see simple_mapping_string_lookup + */ PMOD_EXPORT struct svalue *low_mapping_string_lookup(struct mapping *m, struct pike_string *p); + +/** A shortcut function for inserting an entry into a mapping for cases + * where the key is a Pike string. + * + * @param m mapping to insert the new entry into + * @param p a Pike string to be used as the new entry key + * @param val an svalue representing the new entry's value + * @see mapping_insert + * @see low_mapping_insert + * @see mapping_string_insert_string + */ PMOD_EXPORT void mapping_string_insert(struct mapping *m, struct pike_string *p, struct svalue *val); + +/** A shortcut function for inserting an entry into a mapping for cases + * where both the key and the value are Pike strings. + * + * @param m mapping to insert the new entry into + * @param p a Pike string to be used as the new entry key + * @param val a Pike string to be used as the new entry's value + * @see mapping_string_insert + * @see low_mapping_insert + * @see mapping_string_insert + */ PMOD_EXPORT void mapping_string_insert_string(struct mapping *m, struct pike_string *p, struct pike_string *val); + +/** A shortcut function to look up an entry in a mapping using a C string + * as the key. The function converts the C string into a Pike string and + * then calls @ref low_mapping_string_lookup to do the work. If your code + * looks up an item in mappings very often and you are using a constant C + * string for that, it will be more beneficial to allocate a Pike string + * yourself in the initialization section of your module and then use it + * with @ref low_mapping_string_lookup instead of calling simple_mapping_string_lookup. + * The advantage is not very big since this function allocates the Pike + * string only once, the first time it is used (or when it gets garbage- + * collected), but it is a small optimization nevertheless. + * + * @param m mapping to look up the entry in + * @param p string to be used as the lookup key + * @return an svalue representing the looked up entry's value or NULL if no + * such entry was found + * @see low_mapping_string_lookup + * @see simple_mapping_string_lookup + * @see low_mapping_lookup + */ PMOD_EXPORT struct svalue *simple_mapping_string_lookup(struct mapping *m, const char *p); + +/** First look up @b key1 in the passed mapping and check whether the returned + * value, if any, is a mapping itself. If it is a mapping, look it up using + * @b key2 and return the retrieved entry's value, if any. If key1 lookup in + * the @b m mapping doesn't return a mapping and @b create is not 0 allocate + * a new mapping, insert it in @b m and use for lookup with @b key2. If @b key2 + * lookup doesn't yield a value in neither of the above cases and @b create is not + * 0, allocate a new svalue representing an undefined number, insert it into the + * mapping retrieved (or allocated) during the @b key1 lookup and then perform a + * @b key2 lookup on the mapping retrieved (or allocated) during the @b key1 and + * return the result. + * + * @param m primary mapping to perform a @b key1 lookup on + * @param key1 key used to lookup an entry in the primary mapping @b m + * @param key2 key used to lookup an entry in the secondary mapping retrieved + * (or allocated) as the result of the @b key1 lookup + * @param create 0 to not insert an entry into neither mapping if it cannot be + * found in the mapping, not 0 to insert such entry. + * @return the result of the @b key2 lookup or 0 if either @b key1 or @b key2 + * returned no value and @b create was 0 + * + * @see low_mapping_lookup + */ PMOD_EXPORT struct svalue *mapping_mapping_lookup(struct mapping *m, struct svalue *key1, struct svalue *key2, int create); + +/** A shortcut for @ref mapping_mapping_lookup when both keys are Pike strings. + * For the (complicated) description of what the function does, see the documentation + * of the @ref mapping_mapping_lookup. + * + * @param m primary mapping to perform a @b key1 lookup on + * @param key1 Pike string used to lookup an entry in the primary mapping @b m + * @param key2 Pike string used to lookup an entry in the secondary mapping retrieved + * (or allocated) as the result of the @b key1 lookup + * @param create 0 to not insert an entry into neither mapping if it cannot be + * found in the mapping, not 0 to insert such entry. + * @return the result of the @b key2 lookup or 0 if either @b key1 or @b key2 + * returned no value and @b create was 0 + * + * @see low_mapping_lookup + * @see mapping_mapping_lookup + */ PMOD_EXPORT struct svalue *mapping_mapping_string_lookup(struct mapping *m, struct pike_string *key1, struct pike_string *key2,