CQDB Writer API


Detailed Description

The CQDB Writer API constructs a CQDB chunk on a seekable stream.

The seekable stream must be created by the fopen() function with writable and binary flags ("wb"). The CQDB Writer API can build a CQDB chunk at any position on the stream; one can thus write some data, append a CQDB chunk, and continue writing other data on the stream.

By default, the function cqdb_writer() constructs a database with forward (string to integer identifier) and backward (integer identifier to string) lookups. The data for reverse lookup is omitted with CQDB_ONEWAY flag specified.

It is recommended to keep the maximum number of identifiers as smallest as possible because reverse lookup is maintained by a array with the size of sizeof(int) * (maximum number of identifiers + 1). For example, putting a set of integer identifers (0, 1, 1000) creates a reverse lookup array with 1001 elements only to waste the disk space for 998 (= 1001-3) elements in the array.


Typedefs

typedef tag_cqdb_writer cqdb_writer_t
 Typedef of a CQDB writer.

Functions

cqdb_writer_tcqdb_writer (FILE *fp, int flag)
 Create a new CQDB writer on a seekable stream.
int cqdb_writer_put (cqdb_writer_t *dbw, const char *str, int id)
 Put a string/identifier association to the database.
int cqdb_writer_close (cqdb_writer_t *dbw)
 Close a CQDB writer.


Function Documentation

cqdb_writer_t* cqdb_writer ( FILE *  fp,
int  flag 
)

Create a new CQDB writer on a seekable stream.

This function initializes a database on the seekable stream and returns the pointer to a cqdb_writer_t instance to write the database. The stream must have the writable and binary flags. The database creation flag must be zero except when the reverse lookup array is unnecessary; specifying CQDB_ONEWAY flag will save the storage space for the reverse lookup array. Once calling this function, one should avoid accessing the seekable stream directly until calling cqdb_writer_close().

Parameters:
fp The pointer to the writable and seekable stream.
flag Database creation flag.
Return values:
cqdb_writer_t* The pointer to the new cqdb_writer_t instance if successful; otherwise NULL.

int cqdb_writer_close ( cqdb_writer_t dbw  ) 

Close a CQDB writer.

This function finalizes the database on the stream. If successful, the data remaining on the memory is flushed to the stream; the stream position is moved to the end of the chunk. If an unexpected error occurs, this function tries to rewind the stream position to the original position when the function cqdb_writer() was called.

Parameters:
dbw The pointer to the cqdb_writer_t instance.
Return values:
int Zero if successful, or a status code otherwise.

int cqdb_writer_put ( cqdb_writer_t dbw,
const char *  str,
int  id 
)

Put a string/identifier association to the database.

This function append a string/identifier association into the database. Make sure that the string and/or identifier have never been inserted to the database and that the identifier is a non-negative value.

Parameters:
dbw The pointer to the cqdb_writer_t instance.
str The pointer to the string.
id The identifier.
Return values:
int Zero if successful, or a status code otherwise.


Copyright (c) 2002-2007 by Naoaki Okazaki
Sat Dec 1 18:09:35 2007