summaryrefslogtreecommitdiff
path: root/src/common/db.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/common/db.h')
-rw-r--r--src/common/db.h257
1 files changed, 190 insertions, 67 deletions
diff --git a/src/common/db.h b/src/common/db.h
index e53ace0e6..49a95a135 100644
--- a/src/common/db.h
+++ b/src/common/db.h
@@ -16,12 +16,12 @@
* released. *
* *
* TODO: *
- * - create an enum for the data (with int, unsigned int and void *) *
* - create a custom database allocator *
* - see what functions need or should be added to the database interface *
* *
* HISTORY: *
- * 2007/11/09 - Added an iterator to the database.
+ * 2012/03/09 - Added enum for data types (int, uint, void*) *
+ * 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 *
@@ -50,7 +50,9 @@
* DBType - Enumeration of database types. *
* DBOptions - Bitfield enumeration of database options. *
* DBKey - Union of used key types. *
- * DBApply - Format of functions applyed to the databases. *
+ * DBDataType - Enumeration of data types. *
+ * DBData - Struct for used data types. *
+ * DBApply - Format of functions applied to the databases. *
* DBMatcher - Format of matchers used in DBMap::getall. *
* DBComparator - Format of the comparators used by the databases. *
* DBHasher - Format of the hashers used by the databases. *
@@ -146,33 +148,65 @@ typedef union DBKey {
} DBKey;
/**
- * Format of funtions that create the data for the key when the entry doesn't
+ * Supported types of database data.
+ * @param DB_DATA_INT Uses ints for data.
+ * @param DB_DATA_UINT Uses unsigned ints for data.
+ * @param DB_DATA_PTR Uses void pointers for data.
+ * @public
+ * @see #DBData
+ */
+typedef enum DBDataType {
+ DB_DATA_INT,
+ DB_DATA_UINT,
+ DB_DATA_PTR
+} DBDataType;
+
+/**
+ * Struct for data types used by the database.
+ * @param type Type of data
+ * @param u Union of available data types
+ * @param u.i Data of int type
+ * @param u.ui Data of unsigned int type
+ * @param u.ptr Data of void* type
+ * @public
+ */
+typedef struct DBData {
+ DBDataType type;
+ union {
+ int i;
+ unsigned int ui;
+ void *ptr;
+ } u;
+} DBData;
+
+/**
+ * Format of functions that create the data for the key when the entry doesn't
* exist in the database yet.
* @param key Key of the database entry
- * @param args Extra arguments of the funtion
+ * @param args Extra arguments of the function
* @return Data identified by the key to be put in the database
* @public
* @see DBMap#vensure
* @see DBMap#ensure
*/
-typedef void* (*DBCreateData)(DBKey key, va_list args);
+typedef DBData (*DBCreateData)(DBKey key, va_list args);
/**
- * Format of functions to be applyed to an unspecified quantity of entries of
+ * Format of functions to be applied to an unspecified quantity of entries of
* a database.
* Any function that applies this function to the database will return the sum
* of values returned by this function.
* @param key Key of the database entry
* @param data Data of the database entry
- * @param args Extra arguments of the funtion
- * @return Value to be added up by the funtion that is applying this
+ * @param args Extra arguments of the function
+ * @return Value to be added up by the function that is applying this
* @public
* @see DBMap#vforeach
* @see DBMap#foreach
* @see DBMap#vdestroy
* @see DBMap#destroy
*/
-typedef int (*DBApply)(DBKey key, void* data, va_list args);
+typedef int (*DBApply)(DBKey key, DBData *data, va_list args);
/**
* Format of functions that match database entries.
@@ -185,7 +219,7 @@ typedef int (*DBApply)(DBKey key, void* data, va_list args);
* @public
* @see DBMap#getall
*/
-typedef int (*DBMatcher)(DBKey key, void* data, va_list args);
+typedef int (*DBMatcher)(DBKey key, DBData data, va_list args);
/**
* Format of the comparators used internally by the database system.
@@ -225,7 +259,7 @@ typedef unsigned int (*DBHasher)(DBKey key, unsigned short maxlen);
* @see #db_default_releaser(DBType,DBOptions)
* @see #db_custom_release(DBRelease)
*/
-typedef void (*DBReleaser)(DBKey key, void* data, DBRelease which);
+typedef void (*DBReleaser)(DBKey key, DBData data, DBRelease which);
@@ -255,7 +289,7 @@ struct DBIterator
* @return Data of the entry
* @protected
*/
- void* (*first)(DBIterator* self, DBKey* out_key);
+ DBData* (*first)(DBIterator* self, DBKey* out_key);
/**
* Fetches the last entry in the database.
@@ -266,7 +300,7 @@ struct DBIterator
* @return Data of the entry
* @protected
*/
- void* (*last)(DBIterator* self, DBKey* out_key);
+ DBData* (*last)(DBIterator* self, DBKey* out_key);
/**
* Fetches the next entry in the database.
@@ -277,7 +311,7 @@ struct DBIterator
* @return Data of the entry
* @protected
*/
- void* (*next)(DBIterator* self, DBKey* out_key);
+ DBData* (*next)(DBIterator* self, DBKey* out_key);
/**
* Fetches the previous entry in the database.
@@ -288,7 +322,7 @@ struct DBIterator
* @return Data of the entry
* @protected
*/
- void* (*prev)(DBIterator* self, DBKey* out_key);
+ DBData* (*prev)(DBIterator* self, DBKey* out_key);
/**
* Returns true if the fetched entry exists.
@@ -303,14 +337,15 @@ struct DBIterator
/**
* 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.
+ * is fetched
+ * Puts data of the removed entry in out_data, if out_data is not NULL.
* @param self Iterator
- * @return The data of the entry or NULL if not found
+ * @param out_data Data of the removed entry.
+ * @return 1 if entry was removed, 0 otherwise
* @protected
* @see DBMap#remove
*/
- void* (*remove)(DBIterator* self);
+ int (*remove)(DBIterator* self, DBData *out_data);
/**
* Destroys this iterator and unlocks the database.
@@ -350,13 +385,13 @@ struct DBMap {
bool (*exists)(DBMap* self, DBKey key);
/**
- * Get the data of the entry identifid by the key.
+ * Get the data of the entry identified by the key.
* @param self Database
* @param key Key that identifies the entry
* @return Data of the entry or NULL if not found
* @protected
*/
- void* (*get)(DBMap* self, DBKey key);
+ DBData* (*get)(DBMap* self, DBKey key);
/**
* Just calls {@link DBMap#vgetall}.
@@ -375,7 +410,7 @@ struct DBMap {
* @protected
* @see DBMap#vgetall(DBMap*,void **,unsigned int,DBMatcher,va_list)
*/
- unsigned int (*getall)(DBMap* self, void** buf, unsigned int max, DBMatcher match, ...);
+ unsigned int (*getall)(DBMap* self, DBData** buf, unsigned int max, DBMatcher match, ...);
/**
* Get the data of the entries matched by <code>match</code>.
@@ -393,7 +428,7 @@ struct DBMap {
* @protected
* @see DBMap#getall(DBMap*,void **,unsigned int,DBMatcher,...)
*/
- unsigned int (*vgetall)(DBMap* self, void** buf, unsigned int max, DBMatcher match, va_list args);
+ unsigned int (*vgetall)(DBMap* self, DBData** buf, unsigned int max, DBMatcher match, va_list args);
/**
* Just calls {@link DBMap#vensure}.
@@ -408,7 +443,7 @@ struct DBMap {
* @protected
* @see DBMap#vensure(DBMap*,DBKey,DBCreateData,va_list)
*/
- void* (*ensure)(DBMap* self, DBKey key, DBCreateData create, ...);
+ DBData* (*ensure)(DBMap* self, DBKey key, DBCreateData create, ...);
/**
* Get the data of the entry identified by the key.
@@ -422,37 +457,39 @@ struct DBMap {
* @protected
* @see DBMap#ensure(DBMap*,DBKey,DBCreateData,...)
*/
- void* (*vensure)(DBMap* self, DBKey key, DBCreateData create, va_list args);
+ DBData* (*vensure)(DBMap* self, DBKey key, DBCreateData create, va_list args);
/**
* Put the data identified by the key in the database.
- * Returns the previous data if the entry exists or NULL.
+ * Puts the previous data in out_data, if out_data is not NULL.
* NOTE: Uses the new key, the old one is released.
* @param self Database
* @param key Key that identifies the data
* @param data Data to be put in the database
- * @return The previous data if the entry exists or NULL
+ * @param out_data Previous data if the entry exists
+ * @return 1 if if the entry already exists, 0 otherwise
* @protected
*/
- void* (*put)(DBMap* self, DBKey key, void* data);
+ int (*put)(DBMap* self, DBKey key, DBData data, DBData *out_data);
/**
* Remove an entry from the database.
- * Returns the data of the entry.
+ * Puts the previous data in out_data, if out_data is not NULL.
* NOTE: The key (of the database) is released.
* @param self Database
* @param key Key that identifies the entry
- * @return The data of the entry or NULL if not found
+ * @param out_data Previous data if the entry exists
+ * @return 1 if if the entry already exists, 0 otherwise
* @protected
*/
- void* (*remove)(DBMap* self, DBKey key);
+ int (*remove)(DBMap* self, DBKey key, DBData *out_data);
/**
* Just calls {@link DBMap#vforeach}.
* Apply <code>func</code> to every entry in the database.
* Returns the sum of values returned by func.
* @param self Database
- * @param func Function to be applyed
+ * @param func Function to be applied
* @param ... Extra arguments for func
* @return Sum of the values returned by func
* @protected
@@ -464,7 +501,7 @@ struct DBMap {
* Apply <code>func</code> to every entry in the database.
* Returns the sum of values returned by func.
* @param self Database
- * @param func Function to be applyed
+ * @param func Function to be applied
* @param args Extra arguments for func
* @return Sum of the values returned by func
* @protected
@@ -475,11 +512,11 @@ struct DBMap {
/**
* Just calls {@link DBMap#vclear}.
* Removes all entries from the database.
- * Before deleting an entry, func is applyed to it.
+ * Before deleting an entry, func is applied to it.
* Releases the key and the data.
* Returns the sum of values returned by func, if it exists.
* @param self Database
- * @param func Function to be applyed to every entry before deleting
+ * @param func Function to be applied to every entry before deleting
* @param ... Extra arguments for func
* @return Sum of values returned by func
* @protected
@@ -489,11 +526,11 @@ struct DBMap {
/**
* Removes all entries from the database.
- * Before deleting an entry, func is applyed to it.
+ * Before deleting an entry, func is applied to it.
* Releases the key and the data.
* Returns the sum of values returned by func, if it exists.
* @param self Database
- * @param func Function to be applyed to every entry before deleting
+ * @param func Function to be applied to every entry before deleting
* @param args Extra arguments for func
* @return Sum of values returned by func
* @protected
@@ -504,13 +541,13 @@ struct DBMap {
/**
* Just calls {@link DBMap#vdestroy}.
* Finalize the database, feeing all the memory it uses.
- * Before deleting an entry, func is applyed to it.
+ * Before deleting an entry, func is applied to it.
* Releases the key and the data.
* Returns the sum of values returned by func, if it exists.
* NOTE: This locks the database globally. Any attempt to insert or remove
* a database entry will give an error and be aborted (except for clearing).
* @param self Database
- * @param func Function to be applyed to every entry before deleting
+ * @param func Function to be applied to every entry before deleting
* @param ... Extra arguments for func
* @return Sum of values returned by func
* @protected
@@ -520,12 +557,12 @@ struct DBMap {
/**
* Finalize the database, feeing all the memory it uses.
- * Before deleting an entry, func is applyed to it.
+ * Before deleting an entry, func is applied to it.
* Returns the sum of values returned by func, if it exists.
* NOTE: This locks the database globally. Any attempt to insert or remove
* a database entry will give an error and be aborted (except for clearing).
* @param self Database
- * @param func Function to be applyed to every entry before deleting
+ * @param func Function to be applied to every entry before deleting
* @param args Extra arguments for func
* @return Sum of values returned by func
* @protected
@@ -559,33 +596,61 @@ struct DBMap {
};
-//For easy access to the common functions.
+// For easy access to the common functions.
+
#define db_exists(db,k) ( (db)->exists((db),(k)) )
#define idb_exists(db,k) ( (db)->exists((db),db_i2key(k)) )
#define uidb_exists(db,k) ( (db)->exists((db),db_ui2key(k)) )
#define strdb_exists(db,k) ( (db)->exists((db),db_str2key(k)) )
-#define db_get(db,k) ( (db)->get((db),(k)) )
-#define idb_get(db,k) ( (db)->get((db),db_i2key(k)) )
-#define uidb_get(db,k) ( (db)->get((db),db_ui2key(k)) )
-#define strdb_get(db,k) ( (db)->get((db),db_str2key(k)) )
-
-#define db_put(db,k,d) ( (db)->put((db),(k),(d)) )
-#define idb_put(db,k,d) ( (db)->put((db),db_i2key(k),(d)) )
-#define uidb_put(db,k,d) ( (db)->put((db),db_ui2key(k),(d)) )
-#define strdb_put(db,k,d) ( (db)->put((db),db_str2key(k),(d)) )
-
-#define db_remove(db,k) ( (db)->remove((db),(k)) )
-#define idb_remove(db,k) ( (db)->remove((db),db_i2key(k)) )
-#define uidb_remove(db,k) ( (db)->remove((db),db_ui2key(k)) )
-#define strdb_remove(db,k) ( (db)->remove((db),db_str2key(k)) )
+// Get pointer-type data from DBMaps of various key types
+#define db_get(db,k) ( db_data2ptr((db)->get((db),(k))) )
+#define idb_get(db,k) ( db_data2ptr((db)->get((db),db_i2key(k))) )
+#define uidb_get(db,k) ( db_data2ptr((db)->get((db),db_ui2key(k))) )
+#define strdb_get(db,k) ( db_data2ptr((db)->get((db),db_str2key(k))) )
+
+// Get int-type data from DBMaps of various key types
+#define db_iget(db,k) ( db_data2i((db)->get((db),(k))) )
+#define idb_iget(db,k) ( db_data2i((db)->get((db),db_i2key(k))) )
+#define uidb_iget(db,k) ( db_data2i((db)->get((db),db_ui2key(k))) )
+#define strdb_iget(db,k) ( db_data2i((db)->get((db),db_str2key(k))) )
+
+// Get uint-type data from DBMaps of various key types
+#define db_uiget(db,k) ( db_data2ui((db)->get((db),(k))) )
+#define idb_uiget(db,k) ( db_data2ui((db)->get((db),db_i2key(k))) )
+#define uidb_uiget(db,k) ( db_data2ui((db)->get((db),db_ui2key(k))) )
+#define strdb_uiget(db,k) ( db_data2ui((db)->get((db),db_str2key(k))) )
+
+// Put pointer-type data into DBMaps of various key types
+#define db_put(db,k,d) ( (db)->put((db),(k),db_ptr2data(d),NULL) )
+#define idb_put(db,k,d) ( (db)->put((db),db_i2key(k),db_ptr2data(d),NULL) )
+#define uidb_put(db,k,d) ( (db)->put((db),db_ui2key(k),db_ptr2data(d),NULL) )
+#define strdb_put(db,k,d) ( (db)->put((db),db_str2key(k),db_ptr2data(d),NULL) )
+
+// Put int-type data into DBMaps of various key types
+#define db_iput(db,k,d) ( (db)->put((db),(k),db_i2data(d)) )
+#define idb_iput(db,k,d) ( (db)->put((db),db_i2key(k),db_i2data(d)) )
+#define uidb_iput(db,k,d) ( (db)->put((db),db_ui2key(k),db_i2data(d)) )
+#define strdb_iput(db,k,d) ( (db)->put((db),db_str2key(k),db_i2data(d)) )
+
+// Put uint-type data into DBMaps of various key types
+#define db_uiput(db,k,d) ( (db)->put((db),(k),db_ui2data(d)) )
+#define idb_uiput(db,k,d) ( (db)->put((db),db_i2key(k),db_ui2data(d)) )
+#define uidb_uiput(db,k,d) ( (db)->put((db),db_ui2key(k),db_ui2data(d)) )
+#define strdb_uiput(db,k,d) ( (db)->put((db),db_str2key(k),db_ui2data(d)) )
+
+// Remove entry from DBMaps of various key types
+#define db_remove(db,k) ( (db)->remove((db),(k),NULL) )
+#define idb_remove(db,k) ( (db)->remove((db),db_i2key(k),NULL) )
+#define uidb_remove(db,k) ( (db)->remove((db),db_ui2key(k),NULL) )
+#define strdb_remove(db,k) ( (db)->remove((db),db_str2key(k),NULL) )
//These are discarding the possible vargs you could send to the function, so those
//that require vargs must not use these defines.
-#define db_ensure(db,k,f) ( (db)->ensure((db),(k),(f)) )
-#define idb_ensure(db,k,f) ( (db)->ensure((db),db_i2key(k),(f)) )
-#define uidb_ensure(db,k,f) ( (db)->ensure((db),db_ui2key(k),(f)) )
-#define strdb_ensure(db,k,f) ( (db)->ensure((db),db_str2key(k),(f)) )
+#define db_ensure(db,k,f) ( db_data2ptr((db)->ensure((db),(k),(f))) )
+#define idb_ensure(db,k,f) ( db_data2ptr((db)->ensure((db),db_i2key(k),(f))) )
+#define uidb_ensure(db,k,f) ( db_data2ptr((db)->ensure((db),db_ui2key(k),(f))) )
+#define strdb_ensure(db,k,f) ( db_data2ptr((db)->ensure((db),db_str2key(k),(f))) )
// Database creation and destruction macros
#define idb_alloc(opt) db_alloc(__FILE__,__LINE__,DB_INT,(opt),sizeof(int))
@@ -597,10 +662,11 @@ struct DBMap {
#define db_clear(db) ( (db)->clear(db,NULL) )
#define db_size(db) ( (db)->size(db) )
#define db_iterator(db) ( (db)->iterator(db) )
-#define dbi_first(dbi) ( (dbi)->first(dbi,NULL) )
-#define dbi_last(dbi) ( (dbi)->last(dbi,NULL) )
-#define dbi_next(dbi) ( (dbi)->next(dbi,NULL) )
-#define dbi_prev(dbi) ( (dbi)->prev(dbi,NULL) )
+#define dbi_first(dbi) ( db_data2ptr((dbi)->first(dbi,NULL)) )
+#define dbi_last(dbi) ( db_data2ptr((dbi)->last(dbi,NULL)) )
+#define dbi_next(dbi) ( db_data2ptr((dbi)->next(dbi,NULL)) )
+#define dbi_prev(dbi) ( db_data2ptr((dbi)->prev(dbi,NULL)) )
+#define dbi_remove(dbi) ( (dbi)->remove(dbi,NULL) )
#define dbi_exists(dbi) ( (dbi)->exists(dbi) )
#define dbi_destroy(dbi) ( (dbi)->destroy(dbi) )
@@ -616,8 +682,14 @@ struct DBMap {
* db_i2key - Manual cast from 'int' to 'DBKey'. *
* db_ui2key - Manual cast from 'unsigned int' to 'DBKey'. *
* db_str2key - Manual cast from 'unsigned char *' to 'DBKey'. *
- * db_init - Initialise the database system. *
- * db_final - Finalise the database system. *
+ * db_i2data - Manual cast from 'int' to 'DBData'. *
+ * db_ui2data - Manual cast from 'unsigned int' to 'DBData'. *
+ * db_ptr2data - Manual cast from 'void*' to 'DBData'. *
+ * db_data2i - Gets 'int' value from 'DBData'. *
+ * db_data2ui - Gets 'unsigned int' value from 'DBData'. *
+ * db_data2ptr - Gets 'void*' value from 'DBData'. *
+ * db_init - Initializes the database system. *
+ * db_final - Finalizes the database system. *
\*****************************************************************************/
/**
@@ -730,6 +802,57 @@ DBKey db_ui2key(unsigned int key);
DBKey db_str2key(const char *key);
/**
+ * Manual cast from 'int' to the struct DBData.
+ * @param data Data to be casted
+ * @return The data as a DBData struct
+ * @public
+ */
+DBData db_i2data(int data);
+
+/**
+ * Manual cast from 'unsigned int' to the struct DBData.
+ * @param data Data to be casted
+ * @return The data as a DBData struct
+ * @public
+ */
+DBData db_ui2data(unsigned int data);
+
+/**
+ * Manual cast from 'void *' to the struct DBData.
+ * @param data Data to be casted
+ * @return The data as a DBData struct
+ * @public
+ */
+DBData db_ptr2data(void *data);
+
+/**
+ * Gets int type data from struct DBData.
+ * If data is not int type, returns 0.
+ * @param data Data
+ * @return Integer value of the data.
+ * @public
+ */
+int db_data2i(DBData *data);
+
+/**
+ * Gets unsigned int type data from struct DBData.
+ * If data is not unsigned int type, returns 0.
+ * @param data Data
+ * @return Unsigned int value of the data.
+ * @public
+ */
+unsigned int db_data2ui(DBData *data);
+
+/**
+ * Gets void* type data from struct DBData.
+ * If data is not void* type, returns NULL.
+ * @param data Data
+ * @return Void* value of the data.
+ * @public
+ */
+void* db_data2ptr(DBData *data);
+
+/**
* Initialize the database system.
* @public
* @see #db_final(void)