7. Word, End-Word, Exact-Word Searches

Word search, end-word search, and exact-word search are search methods to search the current subbook for entires matched to the given word. Word search looks for entires whose heads are matched to the given word. End-word search looks for entires whose tails are matched to the given word. Exact-word search looks for entires that matches exactly to the given word.

The following is an example of word search. It searches for entries beginning with `librar'.

#define MAX_HITS 50 /* It assumes that book is a variable of EB_Book and */ /* it has already set the current subbook. */ EB_Hit hits[MAX_HITS]; int hitcount; if (eb_search_word(&book, "librar") == -1) { fprintf(stderr, "an error occurs.\n"); exit(1); } hitcount = eb_hit_list(&book, hits, MAX_HITS); if (hitcount == -1) { fprintf(stderr, "an error occurs.\n"); exit(1); }

The function eb_search_word() requests a word search. But, the function doesn't return a hit entry. It is done by eb_hit_list(). eb_hit_list() records hit entries onto hits, and it returns the number of hit entries recorded onto hits. In this example, eb_hit_list() gets MAX_HITS (= 50) entries maximum.

If the current subbook is English dictionary, we will get at least two entries; `library' and `librarian'.

+-------------+-------------+--- | (librarian) | (library) | +-------------+-------------+--- hits[0] hits[1]

(The order of the `library' and `librarian' entries may be different from the above picture.)

Each element in hits holds positions of heading and text of the hit entry.

heading +-----------+ +--->| librarian | +----------+ | +-----------+ | heading ----+ text | | +-------------------------------------+ | text -------->| librarian | +----------+ | n. (1) A person who is a specialist | hits[0] | in library work. (2) ... | +-------------------------------------+

In other words, the element doesn't have heading and text themselves. This chapter doesn't explain how to get heading and text.

7.1 Get Remained Entries
7.2 Data Types
7.3 Functions

7.1 Get Remained Entries

As mentioned before, the second argument to eb_hit_list() is the maximum number of hit entries to be gotten. In the following example, we get only MAX_HITS entries maximum, even if more entries are matched:

hitcount = eb_hit_list(&book, hits, MAX_HITS);

To get the remained entries, please invoke eb_hit_list() repeatedly until it returns 0:

for (;;) { hitcount = eb_hit_list(&book, hits, MAX_HITS); if (hitcount == 0) { break; } else if (hitcount == -1) { fprintf(stderr, "an error occurs.\n"); exit(1); } /* show headings of hit entires */ }

However, the actions described below reset internal repetition status of eb_hit_list(). After the reset, you cannot get the remained entires any longer.

• Call one of the following functions for the EB_Book object.
  • eb_set_subbook()
  • eb_unset_subbook()
  • eb_set_all_subbooks()
  • eb_bind()
  • eb_clear()
  • eb_suspend()

• Call one of the following functions for any EB_Book object.
  • eb_search_word()
  • eb_search_endword()
  • eb_search_exactword()

  • Call one of the following functions for another EB_Book object.
  • eb_hit_list() (see below)

If you invoke eb_hit_list() for an EB_Book object different from that specified at the previous call, an error occurs. In this case, the function returns -1 and it sets eb_error.

The internal repetition status is also reset when eb_hit_list() fails (i.e. it returns -1).

7.2 Data Types

Please include `eb/eb.h' to use the data types described in this section:

#include <eb/eb.h>

Data type: EB_Hit

The data type EB_Hit represents a hit entry of the search. This data type is defined as:

typedef struct { EB_Position heading; EB_Position text; } EB_Hit;

You may access and set the members in this type directly.

Data type: EB_Position

The data type EB_Position represents a position in subbook contents. This data type is defined as:

typedef struct { int page; int offset; } EB_Position;

You may access and set the members in this type directly.

7.3 Functions

Please include `eb/eb.h' to use the functions described in this section:

#include <eb/eb.h>

Function: int eb_have_exactword_search (EB_Book *book)

The function eb_have_exactword_search() returns 1 if the current subbook of book has the exact word search method. It returns 0 and sets eb_error to EB_ERR_NO_SUCH_SEARCH if the current subbook doesn't have the method, or if the current subbook is not set.

Function: int eb_search_exactword (EB_Book *book, const char *inputword)

The function eb_search_exactword() searches the current subbook of book for entries matched exactly to inputword. The current subbook must have been set beforehand. The inputword must be written in EUC-JP or ISO 8859-1 according with the character code of book.

This function only sends a search request to EB Library. It doesn't return a hit entires. Hit entries are gotten by eb_hit_list().

If succeeds, it returns 0. Otherwise, it returns -1, and sets eb_error. subbook.

Function: int eb_have_word_search (EB_Book *book)

The function eb_have_word_search() returns 1 if the current subbook of book has the word search method. It returns 0 and sets eb_error to EB_ERR_NO_SUCH_SEARCH if the current subbook doesn't have the method, or if the current subbook is not set.

Function: int eb_search_word (EB_Book *book, const char *inputword)

The function eb_search_word() searches the current subbook of book for entries whose heads are matched to inputword. The current subbook must have been set beforehand. The inputword may be written in EUC-JP or ISO 8859-1 according with the character code of book.

This function only sends a search request to EB Library. It doesn't return a hit entires. Hit entries are gotten by eb_hit_list().

If succeeds, it returns 0. Otherwise, it returns -1, and sets eb_error.

Function: int eb_have_endword_search (EB_Book *book)

The function eb_have_endword_search() returns 1 if the current subbook of book has the end word search method. It returns 0 and sets eb_error to EB_ERR_NO_SUCH_SEARCH if the current subbook doesn't have the method, or if the current subbook is not set.

Function: int eb_search_endword (EB_Book *book, const char *inputword)

The function eb_endsearch_word() searches the current subbook of book for entries whose tails are matched to inputword. The inputword may be written in EUC-JP or ISO 8859-1 according with the character code of book.

This function only sends a search request to EB Library. It doesn't return a hit entires. Hit entries are gotten by eb_hit_list().

If succeeds, it returns 0. Otherwise, it returns -1, and sets eb_error. subbook.

Function: int eb_hit_list (EB_Book *book, EB_Hit *hits, int maxhits)

The function eb_hit_list() gets hit entries of eb_search_exactword(), eb_search_word(), or eb_search_endword() that was called beforehand. Accordingly, you must have call one of these function successfully before call this function. Otherwise, this function fails.

book passed to eb_hit_list() and passed to eb_search_exactword() (or eb_search_word() or eb_search_endword()) must be the same. This function fails if you give a different EB_Book object to eb_hit_list().

eb_hit_list() puts maxhits hit entries maximum into hits. If eb_hit_list() finds more hit entries, it gets first maxhits entries. You can get remained entries by invoking eb_hit_list() repeatedly until it returns 0 (see section 7.1 Get Remained Entries).

If succeeds, this function returns the number of entries recorded onto hits. Otherwise, it returns -1, and sets eb_error.