1  #ifndef     __TINY_DOUBLE_ARRAY_H_
  2  #define     __TINY_DOUBLE_ARRAY_H_
  3  
  4  
  5  // This library provides a static double-array dictionary which stores
  6  // keys (strings) and their records (user-defined).
  7  
  8  
  9  // Most functions provided by this library return the following error codes.
 10  #define     DA_OK       0       // No error.
 11  #define     DA_EHDL     ( -1 )  // Invalid handle.
 12  #define     DA_EMEM     ( -2 )  // Memory allocation error.
 13  #define     DA_EIO      ( -3 )  // I/O error.
 14  #define     DA_EARG     ( -4 )  // Invalid argument.
 15  #define     DA_EFMT     ( -5 )  // Invalid format.
 16  #define     DA_EMAX     ( -6 )  // Too large.
 17  #define     DA_EVER     ( -7 )  // Version error.
 18  
 19  
 20  #ifdef  __cplusplus
 21  extern  "C" {
 22  #endif
 23  
 24  
 25  // Handle of keyset.
 26  typedef     struct DASet    *hDASet;
 27  
 28  // Handle of dictionary.
 29  typedef     struct DADic    *hDADic;
 30  
 31  // Dictionary status.
 32  typedef     struct DAStat
 33  {
 34      int     nbc;        // Length of array BC.
 35      int     ntail;      // Length of array TAIL.
 36      int     size;       // Size of dictionary (bytes).
 37      int     nkey;       // Number of keys.
 38      int     maxlen;     // Maximum length of keys (except NULL character).
 39      int     boundary;   // Boundary of records.
 40  }   DAStat, *hDAStat;
 41  
 42  // Callback function for enumerating keys.
 43  // This callback receives 3 arguments, 1st one is a key, 2nd one is a pointer
 44  // to record, and 3rd one is the argument which has been passed to DADic_Enum().
 45  // If this function returns other than DA_OK, the enumeration will finish.
 46  typedef     int ( *fDACall )( const char *, void *, void * );
 47  
 48  
 49  // Creates an empty keyset.
 50  int     DASet_Open( hDASet *h );
 51  
 52  // Load a keyset from a text file.
 53  // Delimitors of keys are specified by the 3rd argument.
 54  // For example, if "\t\r\n" has passed as the 3rd argument, tabs, carriage
 55  // returns and line feeds are used as delimitors.
 56  // The 4th argument specifies the size of each record.
 57  int     DASet_Load( hDASet h, const char *path, const char *delim, int rec );
 58  
 59  // Insert a key to a keyset.
 60  // The 3rd argument specifies the size of each record.
 61  int     DASet_Insert( hDASet h, const char *key, int rec );
 62  
 63  // Destroy a keyset.
 64  int     DASet_Close( hDASet h );
 65  
 66  
 67  // Build a dictionary from a keyset.
 68  // The 3rd argument specifies the boundary of records, in other words,
 69  // all records are arranged on the specified byte boundary.
 70  int     DADic_Build( hDADic *h, hDASet set, int boundary );
 71  
 72  // Load a dictionary from a file.
 73  int     DADic_Open( hDADic *h, const char *path );
 74  
 75  // Destroy a dictionary.
 76  int     DADic_Close( hDADic h );
 77  
 78  // Save a dictionary to a file.
 79  int     DADic_Save( hDADic h, const char *path );
 80  
 81  
 82  // Get an information of a dictionary.
 83  int     DADic_Status( hDADic h, hDAStat st );
 84  
 85  // Call a callback function for each key in a dictionary.
 86  // The 2nd argument will be passed to the callback function.
 87  int     DADic_Enum( hDADic h, void *arg, fDACall call );
 88  
 89  // Search a key which equals to an input string.
 90  // If such a key exists, this function returns a pointer to its record.
 91  // In case the key doesn't have a record, non-NULL pointer will be returned.
 92  // If not, this function returns NULL.
 93  void    *DADic_Search( hDADic h, const char *key );
 94  
 95  // Search keys which match a prefix of an input string.
 96  // Each call of this function returns only one key even if there are more than
 97  // one keys to be returned, so this function should be called repeatedly until
 98  // it returns NULL.
 99  // In the 1st call, a pointer to a string and a pointer to an index
100  // zero-cleared must be passed, then this function overwrites the pointers.
101  void    *DADic_Prefix( hDADic h, const char **s, int *idx );
102  
103  // Search keys which appears in an input string.
104  // Similar to DADic_Prefix, each call of this function returns only one key
105  // even if there are more than one keys to be returned, so this function should
106  // be called repeatedly until it returns NULL.
107  // In the 1st call, 2 pointers to a string and a pointer to an index
108  // zero-cleared must be passed, then this function overwrites the pointers.
109  void    *DADic_Infix( hDADic h, const char **start, const char **s, int *idx );
110  
111  
112  // Get an error message from an error code.
113  const char  *DAErr_String( int err );
114  
115  
116  #ifdef  __cplusplus
117  }
118  #endif
119  
120  
121  #endif