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