00001 /** \file
00002  * \brief Attributes Table.
00003  *
00004  * See Copyright Notice in im_lib.h
00005  * $Id: im_attrib.h,v 1.2 2006/11/21 11:56:16 scuri Exp $
00006  */
00007 
00008 #ifndef __IM_ATTRIB_H_
00009 #define __IM_ATTRIB_H_
00010 
00011 #include "im_attrib_flat.h"
00012 
00013 /** \brief Attributes Table.
00014  *
00015  * \par
00016  * All the attributes have a name, a type, a count and the data.\n
00017  * Names are usually strings with less that 30 chars.
00018  * \par
00019  * Attributes are stored in a hash table for fast access. \n
00020  * We use the hash function described in "The Pratice of Programming" of Kernighan & Pike.
00021  * \ingroup util */
00022 class imAttribTable
00023 {
00024   imAttribTablePrivate* ptable; 
00025 public:
00026 
00027   /** Creates an empty table.
00028    * If size is zero the default size of 101 is used. Size must be a prime number. 
00029    * Other common values are 67, 599 and 1499.*/ 
00030   imAttribTable(int hash_size)
00031     { ptable = imAttribTableCreate(hash_size); }
00032 
00033   /** Destroys the table and all the attributes. */
00034   ~imAttribTable()
00035     { imAttribTableDestroy(ptable); ptable = 0; }
00036 
00037   /** Returns the number of elements in the table. */
00038   int Count() const
00039     { return imAttribTableCount(ptable); }
00040 
00041   /** Removes all the attributes in the table */
00042   void RemoveAll()
00043     { imAttribTableRemoveAll(ptable); }
00044 
00045   /** Copies the contents of the given table into this table. */
00046   void CopyFrom(const imAttribTable& table)
00047     { imAttribTableCopyFrom(ptable, table.ptable); }
00048 
00049   /** Inserts an attribute into the table. \n 
00050    * Data is duplicated if not NULL, else data is initialized with zeros.
00051    * See also \ref imDataType. */
00052   void Set(const char* name, int data_type, int count, const void* data)
00053     { imAttribTableSet(ptable, name, data_type, count, data); }
00054 
00055   /** Removes an attribute from the table given its name. */
00056   void UnSet(const char *name)
00057     { imAttribTableUnSet(ptable, name); }
00058 
00059   /** Finds an attribute in the table.
00060    * Returns the attribute if found, NULL otherwise. 
00061    * See also \ref imDataType. */
00062   const void* Get(const char *name, int *data_type = 0, int *count = 0) const
00063     { return imAttribTableGet(ptable, name, data_type, count); }
00064 
00065   /** For each attribute calls the user callback. If the callback returns 0 the function returns. */
00066   void ForEach(void* user_data, imAttribTableCallback attrib_func) const
00067     { imAttribTableForEach(ptable, user_data, attrib_func); }
00068 };
00069 
00070 /** \brief Attributes Table.
00071  *
00072  * \par
00073  * Same as \ref imAttribTable, but uses an array of fixed size.
00074  * \ingroup util */
00075 class imAttribArray
00076 {
00077   imAttribTablePrivate* ptable; 
00078 public:
00079 
00080   /** Creates an empty array. */ 
00081   imAttribArray(int count)
00082     { ptable = imAttribArrayCreate(count); }
00083 
00084   /** Destroys the array and all the attributes. */
00085   ~imAttribArray()
00086     { imAttribTableDestroy(ptable); ptable = 0; }
00087 
00088   /** Returns the number of elements in the array. */
00089   int Count() const
00090     { return imAttribTableCount(ptable); }
00091 
00092   /** Removes all the attributes in the array */
00093   void RemoveAll()
00094     { imAttribTableRemoveAll(ptable); }
00095 
00096   /** Copies the contents of the given table into this table. */
00097   void CopyFrom(const imAttribArray& table)
00098     { imAttribArrayCopyFrom(ptable, table.ptable); }
00099 
00100   /** Inserts an attribute into the array. \n 
00101    * Data is duplicated if not NULL, else data is initialized with zeros.
00102    * See also \ref imDataType. */
00103   void Set(int index, const char* name, int data_type, int count, const void* data)
00104     { imAttribArraySet(ptable, index, name, data_type, count, data); }
00105 
00106   /** Finds an attribute in the array.
00107    * Returns the attribute if found, NULL otherwise.
00108    * See also \ref imDataType. */
00109   const void* Get(int index, char *name = 0, int *data_type = 0, int *count = 0) const
00110     { return imAttribArrayGet(ptable, index, name, data_type, count); }
00111 
00112   /** For each attribute calls the user callback. If the callback returns 0 the function returns. */
00113   void ForEach(void* user_data, imAttribTableCallback attrib_func) const
00114     { imAttribTableForEach(ptable, user_data, attrib_func); }
00115 };
00116 
00117 #endif