* Added a database iterator to db.c/db.h.

git-svn-id: https://rathena.svn.sourceforge.net/svnroot/rathena/trunk@11701 54d463be-8e91-2dee-dedb-b68131a5f0ec

1 files changed, 101 insertions, 0 deletions

diff --git a/src/common/db.h b/src/common/db.h
index 45034c141..ecaed67af 100644
--- a/src/common/db.h
+++ b/src/common/db.h
@@ -21,6 +21,7 @@
  *  - see what functions need or should be added to the database interface   *
  *                                                                           *
  *  HISTORY:                                                                 *
+ *    2007/11/09 - Added an iterator to the database.
  *    2.1 (Athena build #???#) - Portability fix                             *
  *      - Fixed the portability of casting to union and added the functions  *
  *        {@link DBMap#ensure(DBMap,DBKey,DBCreateData,...)} and             *
@@ -56,6 +57,7 @@
  *  DBComparator - Format of the comparators used by the databases.          *
  *  DBHasher     - Format of the hashers used by the databases.              *
  *  DBReleaser   - Format of the releasers used by the databases.            *
+ *  DBIterator   - Database iterator.                                        *
  *  DBMap        - Database interface.                                       *
 \*****************************************************************************/
 
@@ -246,11 +248,99 @@ typedef void (*DBReleaser)(DBKey key, void* data, DBRelease which);
 
 
 
+typedef struct DBIterator DBIterator;
 typedef struct DBMap DBMap;
 
 
 
 /**
+ * Database iterator.
+ * Supports forward iteration, backward iteration and removing entries from the database.
+ * The iterator is initially positioned before the first entry of the database.
+ * While the iterator exists the database is locked internally, so invoke 
+ * {@link DBIterator#destroy} as soon as possible.
+ * @public
+ * @see #DBMap
+ */
+struct DBIterator
+{
+
+	/**
+	 * Fetches the first entry in the database.
+	 * Returns the data of the entry.
+	 * Puts the key in out_key, if out_key is not NULL.
+	 * @param self Iterator
+	 * @param out_key Key of the entry
+	 * @return Data of the entry
+	 * @protected
+	 */
+	void* (*first)(DBIterator* self, DBKey* out_key);
+
+	/**
+	 * Fetches the last entry in the database.
+	 * Returns the data of the entry.
+	 * Puts the key in out_key, if out_key is not NULL.
+	 * @param self Iterator
+	 * @param out_key Key of the entry
+	 * @return Data of the entry
+	 * @protected
+	 */
+	void* (*last)(DBIterator* self, DBKey* out_key);
+
+	/**
+	 * Fetches the next entry in the database.
+	 * Returns the data of the entry.
+	 * Puts the key in out_key, if out_key is not NULL.
+	 * @param self Iterator
+	 * @param out_key Key of the entry
+	 * @return Data of the entry
+	 * @protected
+	 */
+	void* (*next)(DBIterator* self, DBKey* out_key);
+
+	/**
+	 * Fetches the previous entry in the database.
+	 * Returns the data of the entry.
+	 * Puts the key in out_key, if out_key is not NULL.
+	 * @param self Iterator
+	 * @param out_key Key of the entry
+	 * @return Data of the entry
+	 * @protected
+	 */
+	void* (*prev)(DBIterator* self, DBKey* out_key);
+
+	/**
+	 * Returns true if the fetched entry exists.
+	 * The databases entries might have NULL data, so use this to to test if 
+	 * the iterator is done.
+	 * @param self Iterator
+	 * @return true is the entry exists
+	 * @protected
+	 */
+	bool (*exists)(DBIterator* self);
+
+	/**
+	 * Removes the current entry from the database.
+	 * NOTE: {@link DBIterator#exists} will return false until another entry 
+	 *       is fethed
+	 * Returns the data of the entry.
+	 * @param self Iterator
+	 * @return The data of the entry or NULL if not found
+	 * @protected
+	 * @see DBMap#remove
+	 */
+	void* (*remove)(DBIterator* self);
+
+	/**
+	 * Destroys this iterator and unlocks the database.
+	 * @param self Iterator
+	 * @protected
+	 */
+	void (*destroy)(DBIterator* self);
+
+};
+
+/**
  * Public interface of a database. Only contains funtions.
  * All the functions take the interface as the first argument.
  * @public
@@ -259,6 +349,17 @@ typedef struct DBMap DBMap;
 struct DBMap {
 
 	/**
+	 * Returns a new iterator for this database.
+	 * The iterator keeps the database locked until it is destroyed.
+	 * The database will keep functioning normally but will only free internal 
+	 * memory when unlocked, so destroy the iterator as soon as possible.
+	 * @param self Database
+	 * @return New iterator
+	 * @protected
+	 */
+	DBIterator* (*iterator)(DBMap* self);
+
+	/**
 	 * Get the data of the entry identifid by the key.
 	 * @param self Database
 	 * @param key Key that identifies the entry