diff --git a/src/mapping.c b/src/mapping.c
index 70a3d59f4b1ef7991c12a395e652960e1f5c3c9e..0291cf97e2942a64f9c8495859baf6bf826725b8 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.183 2004/09/18 20:50:52 nilsson Exp $
+|| $Id: mapping.c,v 1.184 2005/09/10 02:15:45 grendel Exp $
*/
#include "global.h"
@@ -110,7 +110,8 @@ BLOCK_ALLOC_FILL_PAGES(mapping, 2)
#endif /* !PIKE_MAPPING_KEYPAIR_LOOP */
#ifdef PIKE_DEBUG
-/* This function checks that the type field isn't lacking any bits.
+
+/** This function checks that the type field isn't lacking any bits.
* It is used for debugging purposes only.
*/
static void check_mapping_type_fields(struct mapping *m)
@@ -146,7 +147,7 @@ static struct mapping_data weak_val_empty_data =
static struct mapping_data weak_both_empty_data =
{ PIKE_CONSTANT_MEMOBJ_INIT(1), 1, 0,0,0,0,0,0, MAPPING_WEAK, 0,{0}};
-/* This function allocates the hash table and svalue space for a mapping
+/** This function allocates the hash table and svalue space for a mapping
* struct. The size is the max number of indices that can fit in the
* allocated space.
*/
@@ -212,8 +213,13 @@ static void init_mapping(struct mapping *m,
#endif
}
-/* This function allocates an empty mapping with initial room
+/** This function allocates an empty mapping with initial room
* for 'size' values.
+ *
+ * @param size initial number of values
+ * @return the newly allocated mapping
+ * @see do_free_mapping
+ * @see free_mapping
*/
PMOD_EXPORT struct mapping *debug_allocate_mapping(int size)
{
@@ -264,7 +270,7 @@ PMOD_EXPORT void do_free_mapping(struct mapping *m)
free_mapping(m);
}
-/* This function is used to rehash a mapping without loosing the internal
+/** This function is used to rehash a mapping without loosing the internal
* order in each hash chain. This is to prevent mappings from becoming
* inefficient just after being rehashed.
*/
@@ -340,9 +346,13 @@ static void mapping_rehash_backwards_good(struct mapping_data *md,
md->size++;
}
-/* This function re-allocates a mapping. It adjusts the max no. of
+/** This function re-allocates a mapping. It adjusts the max no. of
* values can be fitted into the mapping. It takes a bit of time to
* run, but is used seldom enough not to degrade preformance significantly.
+ *
+ * @param m the mapping to be rehashed
+ * @param new_size new mappingsize
+ * @return the rehashed mapping
*/
static struct mapping *rehash(struct mapping *m, int new_size)
{
@@ -584,8 +594,8 @@ struct mapping_data *copy_mapping_data(struct mapping_data *md)
#define PREPARE_FOR_INDEX_CHANGE() \
if(md->refs>1) COPYMAP()
-/* This function brings the type fields in the mapping up to speed.
- * I only use it when the type fields MUST be correct, which is not
+/** This function brings the type fields in the mapping up to speed.
+ * It should be used only when the type fields MUST be correct, which is not
* very often.
*/
PMOD_EXPORT void mapping_fix_type_field(struct mapping *m)
@@ -638,13 +648,13 @@ PMOD_EXPORT void mapping_set_flags(struct mapping *m, int flags)
}
-/* This function inserts key:val into the mapping m.
+/** This function inserts key:val into the mapping m.
* Same as doing m[key]=val; in pike.
*
- * overwrite:
- * 0: Do not replace the value if the entry exists.
- * 1: Replace the value if the entry exists.
- * 2: Replace both the index and the value if the entry exists.
+ * @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,
diff --git a/src/mapping.h b/src/mapping.h
index fa0ef823a1eb477a9b40a7c2238d99766e5ae3c1..cebfa9fc69a3cffd81445b2b07445edfd5b8d3ed 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.60 2005/04/08 16:55:53 grubba Exp $
+|| $Id: mapping.h,v 1.61 2005/09/10 02:15:45 grendel Exp $
*/
#ifndef MAPPING_H
@@ -87,6 +87,13 @@ extern struct mapping *gc_internal_mapping;
#endif /* PIKE_MAPPING_KEYPAIR_LOOP */
+/** Free a previously allocated mapping. The preferred method of freeing
+ * a mapping is by calling the @ref do_free_mapping function.
+ *
+ * @param M The mapping to be freed
+ * @see do_free_mapping
+ * @see free_mapping_data
+ */
#define free_mapping(M) do{ \
struct mapping *m_=(M); \
debug_malloc_touch(m_); \
@@ -98,6 +105,14 @@ extern struct mapping *gc_internal_mapping;
really_free_mapping(m_); \
}while(0)
+/** Free only the mapping data leaving the mapping structure itself intact.
+ *
+ * @param M The mapping structure 'data' member of the mapping whose data is to be removed
+ * @see free_mapping
+ * @see really_free_mapping_data
+ * @see mapping_data
+ * @see mapping
+ */
#define free_mapping_data(M) do{ \
struct mapping_data *md_=(M); \
debug_malloc_touch(md_); \
@@ -116,8 +131,32 @@ BLOCK_ALLOC_FILL_PAGES(mapping, 2);
PMOD_EXPORT struct mapping *debug_allocate_mapping(int size);
+
+/** Function that actually frees the mapping data, called by the wrapper
+ * macro free_mapping_data.
+ *
+ * @param M The mapping structure data member of the mapping whose data is to be removed
+ * @see free_mapping
+ * @see really_free_mapping_data
+ * @see mapping_data
+ * @see mapping
+ */
PMOD_EXPORT void really_free_mapping_data(struct mapping_data *md);
+
+/** A wrapper function for the free_mapping macro. Should be used instead of
+ * the macro as it checks whether the passed mapping is NULL or not.
+ *
+ * @param m The mapping to be freed
+ * @see free_mapping
+ */
PMOD_EXPORT void do_free_mapping(struct mapping *m);
+
+/** Makes a copy of the passed mapping data and returns it to the caller.
+ *
+ * @param md The mapping structure data member to be copied
+ * @return Copy of the passed data
+ * @see mapping
+ */
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);
@@ -125,6 +164,17 @@ PMOD_EXPORT void low_mapping_insert(struct mapping *m,
const struct svalue *key,
const struct svalue *val,
int overwrite);
+
+/** Inserts the specified key and value into the indicated mapping. If
+ * the key already exists in the mapping, its value is replaced with the
+ * new one. For other modes of dealing with existing keys you need to
+ * use the @ref low_mapping_insert function.
+ *
+ * @param m mapping the key/value are to be inserted to
+ * @param key the new entry key
+ * @param value the new entry value
+ * @see low_mapping_insert
+ */
PMOD_EXPORT void mapping_insert(struct mapping *m,
const struct svalue *key,
const struct svalue *val);