From eb2bcd441f1bf814b64fcae743503fa4dd258981 Mon Sep 17 00:00:00 2001
From: Michael Beck <beck@ipd.info.uni-karlsruhe.de>
Date: Wed, 26 Oct 2005 16:24:02 +0000
Subject: [PATCH] Fixed documentation speed up pmap_insert()

[r6816]
---
 ir/adt/pmap.c | 40 ++++++++++++++++++---------------
 ir/adt/pmap.h | 61 ++++++++++++++++++++++++++++++---------------------
 2 files changed, 58 insertions(+), 43 deletions(-)

diff --git a/ir/adt/pmap.c b/ir/adt/pmap.c
index 019ebadbe..d60284d25 100644
--- a/ir/adt/pmap.c
+++ b/ir/adt/pmap.c
@@ -1,6 +1,6 @@
 /*
  * Project:     libFIRM
- * File name:   ir/adt/eset.c
+ * File name:   ir/adt/pmap.c
  * Purpose:     Datentyp: Vereinfachte Map (hash-map) zum Speichern von
  *              Zeigern/Adressen -> Zeigern/Adressen.
  * Author:      Hubert Schmid
@@ -25,7 +25,12 @@ struct pmap {
 
 #define INITIAL_SLOTS 64
 
+/** map a pmap into a set */
+#define M2S(map)  (set *)(map)
 
+/**
+ * compare the keys of two entry pairs
+ */
 static int pmap_entry_cmp(const void *p1, const void *p2, size_t size) {
   const pmap_entry *entry1 = p1;
   const pmap_entry *entry2 = p2;
@@ -33,37 +38,36 @@ static int pmap_entry_cmp(const void *p1, const void *p2, size_t size) {
   return entry1->key != entry2->key;
 }
 
+/* Creates a new empty map with an initial number of slots. */
+pmap *pmap_create_ex(int slots) {
+  return (pmap *)new_set(pmap_entry_cmp, slots);
+}
 
 pmap *pmap_create(void) {
-  return (pmap *)new_set(pmap_entry_cmp, INITIAL_SLOTS);
+  return pmap_create_ex(INITIAL_SLOTS);
 }
 
-
 void pmap_destroy(pmap *map) {
-  del_set((set *)map);
+  del_set(M2S(map));
 }
 
 
 void pmap_insert(pmap *map, void *key, void *value) {
-  if (pmap_contains(map, key)) {
-    pmap_entry * entry = pmap_find(map, key);
-    entry->value = value;
-  } else {
-    pmap_entry entry;
-    entry.key = key;
-    entry.value = value;
-    set_insert((set *)map, &entry, sizeof(pmap_entry), HASH_PTR(key));
-  }
+  pmap_entry entry, *p;
+
+  entry.key = key;
+  p = set_insert(M2S(map), &entry, sizeof(pmap_entry), HASH_PTR(key));
+  p->value = value;
 }
 
 
 int pmap_contains(pmap *map, void *key) {
-  return set_find((set *)map, &key, sizeof(pmap_entry), HASH_PTR(key)) != NULL;
+  return set_find(M2S(map), &key, sizeof(pmap_entry), HASH_PTR(key)) != NULL;
 }
 
 
 pmap_entry * pmap_find(pmap *map, void *key) {
-  return (pmap_entry *)set_find((set *)map, &key, sizeof(pmap_entry), HASH_PTR(key));
+  return (pmap_entry *)set_find(M2S(map), &key, sizeof(pmap_entry), HASH_PTR(key));
 }
 
 
@@ -74,15 +78,15 @@ void * pmap_get(pmap *map, void *key) {
 
 
 pmap_entry *pmap_first(pmap *map) {
-  return (pmap_entry *) set_first((set *)map);
+  return (pmap_entry *) set_first(M2S(map));
 }
 
 
 pmap_entry *pmap_next(pmap *map) {
-  return (pmap_entry *) set_next((set *)map);
+  return (pmap_entry *) set_next(M2S(map));
 }
 
 
 void pmap_break(pmap *map) {
-  set_break((set *)map);
+  set_break(M2S(map));
 }
diff --git a/ir/adt/pmap.h b/ir/adt/pmap.h
index c157fcfbc..7470cc488 100644
--- a/ir/adt/pmap.h
+++ b/ir/adt/pmap.h
@@ -14,47 +14,58 @@
 #ifndef _PMAP_H_
 #define _PMAP_H_
 
-/* Map die Adressen auf Adressen abbildet. Der Vergleich und das
- * Hashen findet �ber die Adresse statt. */
-
+/**  A map which maps addresses to addresses. */
 typedef struct pmap pmap;
 
+/**
+ * A key, value pair.
+ */
 typedef struct pmap_entry {
-  void * key;
-  void * value;
+  void *key;    /**< The key. */
+  void *value;  /**< The value. */
 } pmap_entry;
 
 
-/* Erzeugt eine neue leere Map. */
-pmap * pmap_create(void);
+/** Creates a new empty map. */
+pmap *pmap_create(void);
 
-/* L�scht eine Map. */
+/** Creates a new empty map with an initial number of slots. */
+pmap *pmap_create_ex(int slots);
+
+/** Deletes a map. */
 void pmap_destroy(pmap *);
 
-/* F�gt ein Paar (key,value) in die Map ein. Gibt es bereits einen
- * Eintrag mit "key" in er Map, so wird der entsprechende "value"
- * �berschrieben. */
-void pmap_insert(pmap *, void * key, void * value);
+/**
+ *  Inserts a pair (key,value) into the map. If an entry with key
+ * "key" already exists, its "value" is overwritten.
+ */
+void pmap_insert(pmap *map, void * key, void * value);
+
+/** Checks if an entry with key "key" exists. */
+int pmap_contains(pmap *map, void * key);
 
-/* Pr�ft ob ein Eintrag zu "key" exisitiert. */
-int pmap_contains(pmap *, void * key);
+/** Returns the key, value pair of "key". */
+pmap_entry * pmap_find(pmap *map, void * key);
 
-/* Gibt den Eintrag zu "key" zur�ck. */
-pmap_entry * pmap_find(pmap *, void * key);
+/** Returns the value of "key". */
+void * pmap_get(pmap *map, void * key);
 
-/* Gibt f�r den Eintrag zu "key" den "value" zur�ck. */
-void * pmap_get(pmap *, void * key);
+/**
+ * Returns the first entry of a map if the map is not empty.
+ */
+pmap_entry *pmap_first(pmap *map);
 
-/* Mit den Funktionen "pmap_first" und "pmap_next" kann man durch die
- * Map iterieren. Die Funktionen geben einen Zeiger auf einen Eintrag
- * zur�ck (key,value). Die Funktionen geben "NULL" zur�ck, wenn kein
- * weiterer Eintrag existiert. */
-pmap_entry * pmap_first(pmap *);
-pmap_entry * pmap_next(pmap *);
+/**
+ * Returns the next entry of a map or NULL if all entries were visited.
+ */
+pmap_entry *pmap_next(pmap *);
 
 #define pmap_foreach(pmap, curr) \
-	for(curr=pmap_first(pmap); curr; curr=pmap_next(pmap))
+	for (curr = pmap_first(pmap); curr; curr = pmap_next(pmap))
 
+/** Breaks an iteration.
+ *  Must be called, if a iteration ends before p_map_next() returns NULL.
+ */
 void pmap_break(pmap *map);
 
 #endif /* _PMAP_H_ */
-- 
2.20.1