Branch: Tag:

2005-09-11

2005-09-11 00:40:10 by Marek Habersack <mhabersack@novell.com>

more mapping doxygen docs

Rev: src/mapping.c:1.185
Rev: src/mapping.h:1.62

2:   || 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:   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:   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,