00001 /** \file
00002  * \brief Attributes Table.
00003  *
00004  * See Copyright Notice in im_lib.h
00005  * $Id: im_attrib.h,v 1.1 2005/04/02 22:07:00 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   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   const void* Get(const char *name, int *data_type = 0, int *count = 0) const
00061     { return imAttribTableGet(ptable, name, data_type, count); }
00062 
00063   /** For each attribute calls the user callback. If the callback returns 0 the function returns. */
00064   void ForEach(void* user_data, imAttribTableCallback attrib_func) const
00065     { imAttribTableForEach(ptable, user_data, attrib_func); }
00066 };
00067 
00068 /** \brief Attributes Table.
00069  *
00070  * \par
00071  * Same as \ref imAttribTable, but uses an array of fixed size.
00072  * \ingroup util */
00073 class imAttribArray
00074 {
00075   imAttribTablePrivate* ptable; 
00076 public:
00077 
00078   /** Creates an empty array. */ 
00079   imAttribArray(int count)
00080     { ptable = imAttribArrayCreate(count); }
00081 
00082   /** Destroys the array and all the attributes. */
00083   ~imAttribArray()
00084     { imAttribTableDestroy(ptable); ptable = 0; }
00085 
00086   /** Returns the number of elements in the array. */
00087   int Count() const
00088     { return imAttribTableCount(ptable); }
00089 
00090   /** Removes all the attributes in the array */
00091   void RemoveAll()
00092     { imAttribTableRemoveAll(ptable); }
00093 
00094   /** Copies the contents of the given table into this table. */
00095   void CopyFrom(const imAttribArray& table)
00096     { imAttribArrayCopyFrom(ptable, table.ptable); }
00097 
00098   /** Inserts an attribute into the array. \n 
00099    * Data is duplicated if not NULL, else data is initialized with zeros. */
00100   void Set(int index, const char* name, int data_type, int count, const void* data)
00101     { imAttribArraySet(ptable, index, name, data_type, count, data); }
00102 
00103   /** Finds an attribute in the array.
00104    * Returns the attribute if found, NULL otherwise. */
00105   const void* Get(int index, char *name = 0, int *data_type = 0, int *count = 0) const
00106     { return imAttribArrayGet(ptable, index, name, data_type, count); }
00107 
00108   /** For each attribute calls the user callback. If the callback returns 0 the function returns. */
00109   void ForEach(void* user_data, imAttribTableCallback attrib_func) const
00110     { imAttribTableForEach(ptable, user_data, attrib_func); }
00111 };
00112 
00113 #endif