diff options
| -rw-r--r-- | libibex/ChangeLog | 9 | ||||
| -rw-r--r-- | libibex/file.c | 35 | ||||
| -rw-r--r-- | libibex/find.c | 33 | ||||
| -rw-r--r-- | libibex/index.c | 54 | ||||
| -rw-r--r-- | libibex/words.c | 21 |
5 files changed, 144 insertions, 8 deletions
diff --git a/libibex/ChangeLog b/libibex/ChangeLog index a4a15182e2..ba785db21a 100644 --- a/libibex/ChangeLog +++ b/libibex/ChangeLog @@ -1,11 +1,16 @@ +2000-02-25 Dan Winship <danw@helixcode.com> + + * *.c: add gtk-doc-style comments + 2000-02-21 Matt Loper <matt@helixcode.com> * .cvsignore: Added mkindex. 2000-02-21 NotZed <NotZed@HelixCode.com> - * Makefile.am: change noinst_LIBRARIES to noinst_LTLIBRARIES, and supply -static to - LDFLAGS. Duh, and changed LDADD back to libibex.la. + * Makefile.am: change noinst_LIBRARIES to noinst_LTLIBRARIES, and + supply -static to LDFLAGS. Duh, and changed LDADD back to + libibex.la. 2000-02-20 Matt Loper <matt@helixcode.com> diff --git a/libibex/file.c b/libibex/file.c index 57b31af89f..0cf637764e 100644 --- a/libibex/file.c +++ b/libibex/file.c @@ -52,6 +52,16 @@ static void free_word (gpointer key, gpointer value, gpointer data); * line has in common with the line before it, followed by the rest of * the string. Obviously this only really works if the lists are sorted. */ + +/** + * ibex_open: open (or possibly create) an ibex index + * @file: the name of the file + * @create: whether or not to create the file if it doesn't exist. + * + * Open and/or create the named ibex file and return a handle to it. + * + * Return value: an ibex handle, or NULL if an error occurred. + **/ ibex * ibex_open (char *file, gboolean create) { @@ -151,6 +161,9 @@ struct ibex_write_data { char *lastname; }; +/* This is an internal function to find the longest common initial + * prefix between the last-written word and the current word. + */ static int get_prefix (struct ibex_write_data *iwd, char *name) { @@ -219,6 +232,15 @@ write_word (gpointer key, gpointer value, gpointer data) return FALSE; } +/** + * ibex_write: Write an ibex out to disk. + * @ib: the ibex + * + * This writes an ibex to disk. + * + * Return value: 0 for success, -1 for failure (in which case errno + * is set). + **/ int ibex_write (ibex *ib) { @@ -271,6 +293,19 @@ lose: return -1; } +/** + * ibex_close: Write out the ibex file (if it has changed) and free + * the data associated with it. + * @ib: the ibex + * + * If this ibex file has been modified since it was opened, this will + * call ibex_write() to write it out to disk. It will then free all data + * associated with the ibex. After calling ibex_close(), @ib will no + * longer be a valid ibex. + * + * Return value: 0 on success, -1 on an ibex_write() failure (in which + * case @ib will not be destroyed). + **/ int ibex_close (ibex *ib) { diff --git a/libibex/find.c b/libibex/find.c index f449144e61..91e611401c 100644 --- a/libibex/find.c +++ b/libibex/find.c @@ -24,6 +24,19 @@ #include "ibex_internal.h" +/** + * ibex_find: search an ibex for a word + * @ib: an ibex + * @word: the word + * + * This routine searches an ibex for a word and returns a GPtrArray + * containing the names of the files in the ibex that contain the word. + * If no matches are found, it will return an empty array (not NULL). + * The caller must free the array, but MUST NOT free or alter its + * elements. + * + * Return value: the array of filenames containing @word + **/ GPtrArray * ibex_find (ibex *ib, char *word) { @@ -42,6 +55,16 @@ ibex_find (ibex *ib, char *word) return ret; } +/** + * ibex_find_name: Check if a word occurs in a given file + * @ib: an ibex + * @name: a filename + * @word: a word + * + * This checks if the given word occurs in the given file. + * + * Return value: TRUE or FALSE + **/ gboolean ibex_find_name (ibex *ib, char *name, char *word) { @@ -72,6 +95,16 @@ build_array (gpointer key, gpointer value, gpointer data) return FALSE; } +/** + * ibex_find_all: Find files containing multiple words + * @ib: an ibex + * @words: a GPtrArray of words + * + * This works like ibex_find(), but returns an array of filenames + * which contain all of the words in @words. + * + * Return value: an array of matches + **/ GPtrArray * ibex_find_all (ibex *ib, GPtrArray *words) { diff --git a/libibex/index.c b/libibex/index.c index 895cbf50be..5e3e9cf588 100644 --- a/libibex/index.c +++ b/libibex/index.c @@ -28,9 +28,17 @@ #include "ibex_internal.h" -/* Index a file, given its name. (Replace any previously indexed contents - * of this file with the new contents.) - */ +/** + * ibex_index_file: Index a file by name + * @ib: an ibex + * @filename: name of the file to index + * + * This indexes the given file into @ib. If @filename is already in + * the ibex, the existing index entries for it are discarded and the + * file is indexed anew. + * + * Return value: 0 on success, -1 on failure. + **/ int ibex_index_file (ibex *ib, char *filename) { @@ -58,9 +66,27 @@ ibex_index_file (ibex *ib, char *filename) return status; } -/* Given a file descriptor and a name to refer to it by, index LEN - * bytes of data from it. - */ +/** + * ibex_index_fd: Index a file given a file descriptor + * @ib: an ibex + * @name: the name of the file being indexed + * @fd: a file descriptor, open for reading + * @len: the number of bytes to read from the file + * + * This indexes a file, or a part of a file, given an open file + * descriptor and a size. There is no requirement that @name + * actually correspond to @fd in any particular way. + * + * If the function returns successfully, the file descriptor offset of + * @fd will be exactly @len bytes beyond where it was when the + * function was called. The indexer assumes that this point is a word + * boundary. + * + * The behavior of this function is not defined if it is not + * possible to read @len bytes off @fd. + * + * Return value: 0 on success, -1 on failure. + **/ int ibex_index_fd (ibex *ib, char *name, int fd, size_t len) { @@ -83,6 +109,14 @@ ibex_index_fd (ibex *ib, char *name, int fd, size_t len) return status; } +/** + * ibex_unindex: Remove a file from the ibex + * @ib: an ibex + * @name: name of the file to remove + * + * This removes all references to @name from @ib. No memory is freed + * right away, but further searches on @ib will never return @name. + **/ void ibex_unindex (ibex *ib, char *name) { @@ -96,6 +130,14 @@ ibex_unindex (ibex *ib, char *name) } } +/** + * ibex_rename: Rename a file in the ibex + * @ib: an ibex + * @oldname: the old name of the file + * @newname: the new name of the file + * + * This renames a file in the ibex. + **/ void ibex_rename (ibex *ib, char *oldname, char *newname) { diff --git a/libibex/words.c b/libibex/words.c index 1a5a4d5680..40e0452403 100644 --- a/libibex/words.c +++ b/libibex/words.c @@ -184,6 +184,27 @@ ref_word (ibex *ib, ibex_file *ibf, char *word) } } +/** + * ibex_index_buffer: the lowest-level ibex indexing interface + * @ib: an ibex + * @name: the name of the file being indexed + * @buffer: a buffer containing data from the file + * @len: the length of @buffer + * @unread: an output argument containing the number of unread bytes + * + * This routine indexes up to @len bytes from @buffer into @ib. + * If @unread is NULL, the indexer assumes that the buffer ends on a + * word boundary, and will index all the way to the end of the + * buffer. If @unread is not NULL, and the buffer ends with an + * alphabetic character, the indexer will assume that the buffer has + * been cut off in the middle of a word, and return the number of + * un-indexed bytes at the end of the buffer in *@unread. The caller + * should then read in more data through whatever means it has + * and pass in the unread bytes from the original buffer, followed + * by the new data, on its next call. + * + * Return value: 0 on success, -1 on failure. + **/ int ibex_index_buffer (ibex *ib, char *name, char *buffer, size_t len, size_t *unread) |