aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDan Winship <danw@src.gnome.org>2000-02-26 03:36:51 +0800
committerDan Winship <danw@src.gnome.org>2000-02-26 03:36:51 +0800
commitc45670272a6b6e65dbeeecac041db003a6d8d8e8 (patch)
treea51680ffd1041fe70057df8103633cc40a91aa96
parentd59b6744845a963af6048d43e668e58ccfa10158 (diff)
downloadgsoc2013-evolution-c45670272a6b6e65dbeeecac041db003a6d8d8e8.tar.gz
gsoc2013-evolution-c45670272a6b6e65dbeeecac041db003a6d8d8e8.tar.zst
gsoc2013-evolution-c45670272a6b6e65dbeeecac041db003a6d8d8e8.zip
add gtk-doc-style comments
svn path=/trunk/; revision=1936
-rw-r--r--libibex/ChangeLog9
-rw-r--r--libibex/file.c35
-rw-r--r--libibex/find.c33
-rw-r--r--libibex/index.c54
-rw-r--r--libibex/words.c21
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)