@c @appendix The Libdico Library

@menu
* strat::
* argcv::
* lists::
* assoc::
* diag::
* filter::
* parseopt::
* stream::
* url::
* utf8::
* util::
* xlat::
@end menu

@node strat
@section Strategies
@UNREVISED

@smallexample
struct dico_strategy @{
    char *name;
    char *descr;
    dico_select_t sel;
    void *closure;
    int is_default;
@};
@end smallexample

@deftypefn Function dico_strategy_t dico_strategy_dup (const dico_strategy_t @
 @var{strat})
@end deftypefn

@deftypefn Function dico_strategy_t dico_strategy_find (const char *@var{name})
@end deftypefn

@deftypefn Function int dico_strategy_add (const dico_strategy_t @var{strat})
@end deftypefn

@deftypefn Function dico_iterator_t  dico_strategy_iterator (void)
@end deftypefn

@deftypefn Function void dico_strategy_iterate (dico_list_iterator_t @
 @var{itr}, void *@var{data})
@end deftypefn
 
@deftypefn Function size_t dico_strategy_count (void)
@end deftypefn

@deftypefn Function int dico_set_default_strategy (const char *@var{name})
@end deftypefn

@deftypefn Function {const dico_strategy_t} dico_get_default_strategy (void)
@end deftypefn

@deftypefn Function int dico_strategy_is_default_p (dico_strategy_t @var{strat})
@end deftypefn

@node argcv
@section argcv
@UNREVISED

@deftp enum dico_argcv_quoting_style
@end deftp

@deftypevr Variable {enum dico_argcv_quoting_style} dico_argcv_quoting_style
@end deftypevr

@deftypefn Function int dico_argcv_get (const char *@var{command}, @
       const char *@var{delim}, const char *@var{cmnt}, @
       int *@var{argc}, char ***@var{argv})
@deftypefnx Function int dico_argcv_get_n (const char *@var{command}, @
       int @var{len}, @
       const char *@var{delim}, const char *@var{cmnt}, @
       int *@var{argc}, char ***@var{argv})
@deftypefnx Function int dico_argcv_get_np (const char *@var{command}, @
        int @var{len}, @
        const char *@var{delim}, const char *@var{cmnt}, @
        int @var{flags}, @
        int *@var{argc}, char ***@var{argv}, char **@var{endp})
@end deftypefn
  
@deftypefn Function int dico_argcv_string (int @var{argc}, @
  const char **@var{argv}, char **@var{string})
@end deftypefn
  
@deftypefn Function void dico_argcv_free (int @var{argc}, char **@var{argv})
@end deftypefn

@deftypefn Function void dico_argv_free (char **@var{argv})
@end deftypefn

@deftypefn Function int dico_argcv_unquote_char (int @var{c})
@end deftypefn

@deftypefn Function int dico_argcv_quote_char (int @var{c})
@end deftypefn

@deftypefn Function size_t dico_argcv_quoted_length (const char *@var{str}, @
  int *@var{quote})
@end deftypefn

@deftypefn Function void dico_argcv_unquote_copy (char *@var{dst}, @
  const char *@var{src}, size_t @var{n})
@end deftypefn
  
@deftypefn Function void dico_argcv_quote_copy (char *@var{dst}, @
  const char *@var{src})
@end deftypefn
  
@deftypefn Function void dico_argcv_remove (int *@var{argc}, @
  char ***@var{argv}, @
  int (*@var{sel}) (const char *, void *), void *@var{data})
@end deftypefn

@node lists
@section Lists
@UNREVISED

@deftp Type dico_list_t
@end deftp

@deftp Type dico_iterator_t
@end deftp

@deftp {Function Type} dico_list_iterator_t
@smallexample
typedef int (*dico_list_iterator_t)(void *item, void *data);
@end smallexample
@end deftp

@deftp {Function Type} dico_list_comp_t
@smallexample
typedef int (*dico_list_comp_t)(const void *, const void *);
@end smallexample
@end deftp

@deftypefn Function dico_list_t dico_list_create (void)
@end deftypefn

@deftypefn Function void dico_list_destroy (dico_list_t *@var{list}, @
  dico_list_iterator_t @var{free}, void *@var{data})
@end deftypefn
  
@deftypefn Function void dico_list_iterate (dico_list_t @var{list}, @
  dico_list_iterator_t @var{itr}, void *@var{data})
@end deftypefn
  
@deftypefn Function {void *} dico_list_item (dico_list_t @var{list}, @
  size_t @var{n})
@end deftypefn

@deftypefn Function size_t dico_list_count (dico_list_t @var{list})
@end deftypefn

@deftypefn Function int dico_list_append (dico_list_t @var{list}, void *@var{data})
@end deftypefn

@deftypefn Function int dico_list_prepend (dico_list_t @var{list}, void *@var{data})
@deftypefnx Function int dico_list_push (dico_list_t @var{list}, void *@var{data})
@end deftypefn

@deftypefn Function int dico_list_insert_sorted (dico_list_t @var{list}, @
  void *@var{data}, dico_list_comp_t @var{cmp})
@end deftypefn
  
@deftypefn Function dico_list_t dico_list_intersect (dico_list_t @var{a}, @
  dico_list_t @var{b}, dico_list_comp_t @var{cmp})
@end deftypefn
  
@deftypefn Function int dico_list_intersect_p (dico_list_t @var{a}, @
  dico_list_t @var{b}, dico_list_comp_t @var{cmp})
@end deftypefn
  
@deftypefn Function {void *} dico_list_pop (dico_list_t @var{list})
@end deftypefn

@deftypefn Function {void *} dico_list_locate (dico_list_t @var{list}, @
  void *@var{data}, dico_list_comp_t @var{cmp})
@end deftypefn

@deftypefn Function {void *} dico_list_remove (dico_list_t @var{list}, @
  void *@var{data}, dico_list_comp_t @var{cmp})
@end deftypefn

@deftypefn Function {void *} dico_iterator_current (dico_iterator_t @var{itr})
@end deftypefn

@deftypefn Function dico_iterator_t dico_iterator_create (dico_list_t @var{list})
@end deftypefn

@deftypefn Function void dico_iterator_destroy (dico_iterator_t *@var{pitr})
@end deftypefn

@deftypefn Function {void *} dico_iterator_first (dico_iterator_t @var{itr})
@end deftypefn

@deftypefn Function {void *} dico_iterator_next (dico_iterator_t @var{itr})
@end deftypefn

@deftypefn Function {void *} dico_iterator_remove_current (dico_iterator_t @var{itr})
@end deftypefn

@deftypefn Function void dico_iterator_set_data (dico_iterator_t @var{itr}, @
  void *@var{data})
@end deftypefn

@node assoc
@section Associative lists
@UNREVISED

@smallexample
struct dico_assoc @{
    char *key;
    char *value;
@};
@end smallexample

@deftp Type dico_assoc_list_t
@end deftp

@deftypefn Function dico_assoc_list_t dico_assoc_create (void)
@end deftypefn

@deftypefn Function dico_assoc_list_t dico_assoc_dup (dico_assoc_list_t @var{src})
@end deftypefn

@deftypefn Function void dico_assoc_destroy (dico_assoc_list_t *@var{passoc})
@end deftypefn

@deftypefn Function int dico_assoc_clear (dico_assoc_list_t @var{assoc})
@end deftypefn

@deftypefn Function int dico_assoc_add (dico_assoc_list_t @var{assoc}, @
  const char *@var{key}, const char *@var{value})
@end deftypefn

@deftypefn Function int dico_assoc_append (dico_assoc_list_t @var{assoc}, @
  const char *@var{key}, const char *@var{value})
@end deftypefn

@deftypefn Function {const char *}dico_assoc_find_n (@
  dico_assoc_list_t @var{assoc}, @
  const char *@var{key}, size_t @var{n})
@end deftypefn
  
@deftypefn Function {const char *} dico_assoc_find (@
   dico_assoc_list_t @var{assoc},  const char *@var{key})
@end deftypefn

@deftypefn Function void dico_assoc_remove_n (@
   dico_assoc_list_t @var{assoc}, const char *@var{key}, size_t @var{n})
@end deftypefn
   
@deftypefn Function void dico_assoc_remove (@
   dico_assoc_list_t @var{assoc}, const char *@var{key})
@end deftypefn

@deftypefn Function size_t dico_assoc_count (dico_assoc_list_t @var{assoc})
@end deftypefn

@deftypefn Function dico_iterator_t dico_assoc_iterator (@
   dico_assoc_list_t @var{assoc})
@end deftypefn
   
@node diag
@section Diagnostics Functions
@UNREVISED

@table @var
@item L_DEBUG     
@item L_INFO      
@item L_NOTICE    
@item L_WARN      
@item L_ERR       
@item L_CRIT      
@item L_ALERT     
@item L_EMERG     
@end table

@deftypevr Variable {const char *} dico_program_name
@end deftypevr

@deftypevr Variable {const char *} dico_invocation_name
@end deftypevr

@deftypefn Function void dico_set_program_name (char *@var{name})
@end deftypefn

@deftypefn {Function Type} void dico_log_printer_t (@
  int @var{lvl}, int @var{exitcode}, int @var{errcode}, @
  const char *@var{fmt}, @
  va_list @var{ap})
@end deftypefn

@deftypefn Function void dico_set_log_printer (dico_log_printer_t @var{prt})
@end deftypefn

@deftypefn Function void dico_vlog (@
  int @var{lvl}, int @var{errcode}, const char *@var{fmt}, va_list @var{ap})
@end deftypefn
  
@deftypefn Function void dico_log (int @var{lvl}, int @var{errcode}, @
  const char *@var{fmt}, ...)
@end deftypefn
  
@deftypefn Function void dico_die (int @var{exitcode}, int @var{lvl}, @
  int @var{errcode}, char *@var{fmt}, ...)
@end deftypefn

@deftypefn Function int dico_str_to_diag_level (const char *@var{str})
@end deftypefn

@deftypefn Function dico_stream_t dico_log_stream_create (int @var{level})
@end deftypefn

@node filter
@section Filter

@defvr Define FILTER_ENCODE
@end defvr

@defvr Define FILTER_DECODE
@end defvr

@deftp {Function Type} filter_xcode_t
@smallexample
typedef int (*filter_xcode_t) (const char *, size_t,
                   char *, size_t, size_t *, size_t, size_t *);
@end smallexample
@end deftp

@deftypefn Function dico_stream_t filter_stream_create (@
    dico_stream_t @var{str}, @
    size_t @var{min_level}, @
    size_t @var{max_line_length}, @
    filter_xcode_t @var{xcode}, @
    int @var{mode})
@end deftypefn
   
@deftypefn Function dico_stream_t dico_codec_stream_create (@
     const char *@var{encoding}, int @var{mode}, dico_stream_t @
     @var{transport})
@end deftypefn
     

@deftypefn Function dico_stream_t dico_base64_stream_create (@
     dico_stream_t @var{str}, int @var{mode})
@end deftypefn
     
@deftypefn Function dico_stream_t dico_qp_stream_create (@
     dico_stream_t @var{str}, int @var{mode})
@end deftypefn
     
@deftypefn Function int dico_base64_input (char @var{c})
@end deftypefn

@deftypefn Function int dico_base64_decode (@
     const char *@var{iptr}, size_t @var{isize}, @
     char *@var{optr}, size_t @var{osize}, @
     size_t *@var{pnbytes}, @
     size_t @var{line_max}, size_t *@var{pline_len})
@end deftypefn
     
@deftypefn Function int dico_base64_encode (@
     const char *@var{iptr}, size_t @var{isize}, @
     char *@var{optr}, size_t @var{osize}, @
     size_t *@var{pnbytes}, size_t @var{line_max}, @
     size_t *@var{pline_len})
@end deftypefn
     
@deftypefn Function int dico_qp_decode (@
     const char *@var{iptr}, size_t @var{isize}, @
     char *@var{optr}, size_t @var{osize}, @ 
     size_t *@var{pnbytes}, @
     size_t @var{line_max}, size_t *@var{pline_len}) 
@end deftypefn
     
@deftypefn Function int dico_qp_encode (@
     const char *@var{iptr}, size_t @var{isize}, @
     char *@var{optr}, size_t @var{osize}, @
     size_t *@var{pnbytes}, @
     size_t @var{line_max}, size_t *@var{pline_len})
@end deftypefn

@node parseopt
@section parseopt
@UNREVISED

@table @code
@item DICO_PARSEOPT_PARSE_ARGV0
@item DICO_PARSEOPT_PERMUTE
@end table

@deftp Enumeration dico_opt_type

@table @code
@item dico_opt_null
@item dico_opt_bool
@item dico_opt_bitmask
@item dico_opt_bitmask_rev
@item dico_opt_long
@item dico_opt_string
@item dico_opt_enum
@item dico_opt_const
@item dico_opt_const_string
@end table
@end deftp

@deftp struct dico_option

@smallexample
struct dico_option @{
    const char *name;
    size_t len;
    enum dico_opt_type type;
    void *data;
    union @{
        long value;
        const char **enumstr;
    @} v;
    int (*func) (struct dico_option *, const char *);
@};
@end smallexample
@end deftp

@deffn Macro DICO_OPTSTR name
@end deffn

@deftypefn Function int dico_parseopt (struct dico_option *@var{opt}, @
  int @var{argc}, char **@var{argv}, int @var{flags}, int *@var{index})
@end deftypefn
  
@node stream
@section stream
@UNREVISED

@deftypefn Function int dico_stream_create (dico_stream_t *@var{pstream}, @
  int @var{flags}, void *@var{data})
@table @code
@item DICO_STREAM_READ  
@item DICO_STREAM_WRITE  
@item DICO_STREAM_SEEK
@end table
@end deftypefn

@deftypefn Function int dico_stream_open (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function void dico_stream_set_open (@
  dico_stream_t @var{stream}, int (*@var{openfn}) (void *, int))
@end deftypefn
  
@deftypefn Function void dico_stream_set_seek (@
  dico_stream_t @var{stream}, @
  int (*@var{fun_seek}) (void *, off_t, int, off_t *))
@end deftypefn
  
@deftypefn Function void dico_stream_set_size (@
  dico_stream_t @var{stream}, int (*@var{sizefn}) (void *, off_t *))
@end deftypefn
  
@deftypefn Function void dico_stream_set_read (@
  dico_stream_t @var{stream}, @
  int (*@var{readfn}) (void *, char *, size_t, size_t *))
@end deftypefn
  
@deftypefn Function void dico_stream_set_write (@
  dico_stream_t @var{stream}, @
  int (*@var{writefn}) (void *, const char *, size_t, size_t *))
@end deftypefn
  
@deftypefn Function void dico_stream_set_flush (@
  dico_stream_t @var{stream}, int (*@var{flushfn}) (void *))
@end deftypefn
  
@deftypefn Function void dico_stream_set_close (@
  dico_stream_t @var{stream}, int (*@var{closefn}) (void *))
@end deftypefn
  
@deftypefn Function void dico_stream_set_destroy (@
  dico_stream_t @var{stream}, int (*@var{destroyfn}) (void *))
@end deftypefn

@deftypefn Function void dico_stream_set_ioctl (@
  dico_stream_t @var{stream}, int (*@var{ctl}) (void *, int, void *))
@end deftypefn  

@deftypefn Function void dico_stream_set_error_string (@
  dico_stream_t @var{stream}, @
  const char *(*@var{error_string}) (void *, int))
@end deftypefn
  
@deftypefn Function int dico_stream_set_buffer (@
  dico_stream_t @var{stream}, @
  enum dico_buffer_type @var{type}, @
  size_t size)

@deftp Enumeration dico_buffer_type
@table @code
@item dico_buffer_none
@item dico_buffer_line
@item dico_buffer_full
@end table
@end deftp

@end deftypefn

@deftypefn Function off_t dico_stream_seek (@
  dico_stream_t @var{stream}, off_t @var{offset}, int @var{whence})

@table @code
@item DICO_SEEK_SET
@item DICO_SEEK_CUR
@item DICO_SEEK_END
@end table

@end deftypefn

@deftypefn Function int dico_stream_size (dico_stream_t @var{stream}, @
   off_t *@var{psize})
@end deftypefn
   
@deftypefn Function int dico_stream_read_unbuffered (@
  dico_stream_t @var{stream}, @
  void *@var{buf}, size_t @var{size}, @
  size_t *@var{pread})
@end deftypefn
  
@deftypefn Function int dico_stream_write_unbuffered (@
  dico_stream_t @var{stream}, @
  const void *@var{buf}, size_t @var{size}, @
  size_t *@var{pwrite})
@end deftypefn
  
@deftypefn Function int dico_stream_read (@
  dico_stream_t @var{stream},@
  void *@var{buf}, size_t @var{size},@
  size_t *@var{pread})
@end deftypefn
  
@deftypefn Function int dico_stream_readln (@
  dico_stream_t @var{stream},@
  char *@var{buf}, size_t @var{size},@
  size_t *@var{pread})
@end deftypefn
  
@deftypefn Function int dico_stream_getdelim (@
  dico_stream_t @var{stream},@
  char **@var{pbuf}, size_t *@var{psize},@
  int @var{delim}, size_t *@var{pread})
@end deftypefn
  
@deftypefn Function int dico_stream_getline (@
  dico_stream_t @var{stream},@
  char **@var{pbuf}, size_t *@var{psize},@
  size_t *@var{pread})
@end deftypefn
  
@deftypefn Function int dico_stream_write (@
  dico_stream_t @var{stream}, const void *@var{buf}, size_t @var{size})
@end deftypefn
  
@deftypefn Function int dico_stream_writeln (@
  dico_stream_t @var{stream}, const char *@var{buf}, size_t @var{size})
@end deftypefn

@deftypefn Function int dico_stream_ioctl (@
  dico_stream_t @var{stream}, int @var{code}, void *@var{ptr})
@end deftypefn
  
@deftypefn Function {const char *} dico_stream_strerror (@
  dico_stream_t @var{stream}, int @var{rc})
@end deftypefn
  
@deftypefn Function int dico_stream_last_error (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function void dico_stream_clearerr (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function int dico_stream_eof (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function int dico_stream_flush (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function int dico_stream_close (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function void dico_stream_destroy (dico_stream_t *@var{stream})
@end deftypefn

@deftypefn Function off_t dico_stream_bytes_in (dico_stream_t @var{stream})
@end deftypefn

@deftypefn Function off_t dico_stream_bytes_out (dico_stream_t @var{stream})
@end deftypefn

@node url
@section url
@UNREVISED

@deftp struct dico_url
@smallexample
#define DICO_REQUEST_DEFINE 0
#define DICO_REQUEST_MATCH 1

struct dico_request @{
    int type;
    char *word;
    char *database;
    char *strategy;
    unsigned long n;
@};

struct dico_url @{
    char *string;
    char *proto;
    char *host;
    int port;
    char *path;
    char *user;
    char *passwd;
    dico_assoc_list_t args;
    struct dico_request req;
@};
@end smallexample
@end deftp

@deftp Pointer dico_url_t
@end deftp

@deftypefn Function int dico_url_parse (dico_url_t *@var{purl}, @
  const char *@var{str})
@end deftypefn
  
@deftypefn Function void dico_url_destroy (dico_url_t *@var{purl})
@end deftypefn

@deftypefn Function {const char *} dico_url_get_arg (@
  dico_url_t @var{url}, const char *@var{argname})
@end deftypefn
  
@deftypefn Function {char *} dico_url_full_path (dico_url_t @var{url})
@end deftypefn

@node utf8
@section UTF-8

This section describes functions for handling UTF-8 strings.  A UTF-8
character can be represented either as a multi-byte character or a
wide character.

@dfn{Multibyte} character is a @code{char *} pointing to one or more
bytes representing the UTF-8 character.

@dfn{Wide character} is an @code{unsigned} value identifying the
character.

In the discussion below, a sequence of one or more multi-byte
characters is called a @dfn{multi-byte string}.  Multibyte strings
terminate with a single @samp{nul} (0) character.

A sequence of one or more wide characters is called a @dfn{wide
character string}.  Such strings terminate with a single 0 value.

@menu
* Character sizes::
* Iterating over UTF-8 strings::
* Conversions::
* Comparing UTF-8 strings::
* Character lookups::
* Functions for converting UTF-8 characters::
* Additional functions::
@end menu

@node Character sizes
@subsection Character sizes

@deftypefn Function size_t utf8_char_width (const unsigned char *@var{cp})
Returns length in bytes of the UTF-8 character representation pointed
to by @var{cp}.
@end deftypefn

@deftypefn Function size_t utf8_strlen (const char *@var{str})
Returns number of UTF-8 characters (not bytes) in @var{str}.
@end deftypefn

@deftypefn Function size_t utf8_wc_strlen (const unsigned *@var{s})
Returns number of wide characters in the wide character string @var{s}.
@end deftypefn

@node Iterating over UTF-8 strings
@subsection Iterating over UTF-8 strings

@deftp struct utf8_iterator
A data type for iterating over a string of UTF-8 characters.  Defined
as:

@smallexample
struct utf8_iterator @{
    char *string;
    char *curptr;
    unsigned curwidth;
@};
@end smallexample

When iterating over characters in string, @code{curptr} points to the
current character, and @code{curwidth} holds its length in bytes.
@end deftp

@deftypefn Function int utf8_iter_isascii (struct utf8_iterator @var{itr})
Returns @samp{true} if @var{itr} points to a ASCII character.
@end deftypefn

@deftypefn Function int utf8_iter_end_p (struct utf8_iterator *@var{itr})
Returns @samp{true} if @var{itr} reached end of the input string.
@end deftypefn

@deftypefn Function int utf8_iter_first (struct utf8_iterator *@var{itr}, @
  unsigned char *@var{str})
Initializes @var{itr} for iterating over the string @var{str}.
On success, positions @code{@var{itr}.curptr} to the next character
from the input string, sets @code{@var{itr}.curwidth} to the length of
that character in bytes, and returns @samp{0}.  If @var{str} is an
empty string, returns @samp{1}.
@end deftypefn

@deftypefn Function int utf8_iter_next (struct utf8_iterator *@var{itr})
Positions @code{@var{itr}.curptr} to the next character from the input
string.  Sets @code{@var{itr}.curwidth} to the length of that
character in bytes.
@end deftypefn

@node Conversions
@subsection Conversions

The following functions convert between the two string representations.

@deftypefn Function int utf8_mbtowc_internal (void *@var{data}, @
  int (*@var{read}) (void*), unsigned int *@var{pwc})
Internal function for converting a single UTF-8 character to a corresponding
wide character representation.  The character to convert is obtained
by calling the function pointed to by @var{read} with @var{data} as
its only argument.  If that call returns a non-positive value, the
function sets @code{errno} to @samp{ENODATA} and returns -1.
@end deftypefn

@deftypefn Function int utf8_mbtowc (unsigned int *@var{pwc},@
 const char *@var{r}, size_t @var{len})
Converts first @var{len} characters from the multi-byte string @var{r}
to wide character representation.  On success, returns 0 and stores
the result in @var{pwc}.  The result pointer is allocated using
@code{malloc}(3).

On error (invalid multi-byte sequence encountered), returns -1 and sets
@code{errno} to @samp{EILSEQ}. 
@end deftypefn

@deftypefn Function int utf8_wctomb (unsigned char *@var{r}, @
  unsigned int @var{wc})
Stores the UTF-8 representation of the Unicode character wc in @code{r[0..5]}.
Returns the number of bytes stored.  If @var{wc} is out of range,
return -1 and sets @code{errno} to @samp{EILSEQ}.
@end deftypefn

@deftypefn Function int utf8_wc_to_mbstr (const unsigned *@var{word}, @
  size_t @var{wordlen}, char **@var{retptr})
Converts first @var{wordlen} characters of the wide character string
@var{word} to multi-byte representation.  The result is returned in
@var{retptr}.  It is allocated using @code{malloc}(3).

Returns 0 on success.  On error, returns -1 and sets @code{errno} to
one of the following values:

@table @asis
@item ENOMEM
Not enough memory to allocate the return buffer.

@item EILSEQ
An invalid wide character is encountered.
@end table
@end deftypefn

@deftypefn Function int utf8_mbstr_to_wc (const char *@var{str},@
 unsigned **@var{wptr}, size_t *@var{plen})
Converts a multi-byte string from @var{str} to its wide character
representation.

The result is returned in @var{retptr}.  It is allocated using @code{malloc}(3).

Returns 0 on success.  On error, returns -1 and sets @code{errno} to
one of the following values:

@table @asis
@item ENOMEM
Not enough memory to allocate the return buffer.

@item EILSEQ
An invalid wide character is encountered.
@end table 
@end deftypefn
 
@deftypefn Function int utf8_mbstr_to_norm_wc (const char *@var{str}, @
  unsigned **@var{wptr}, size_t *@var{plen})
Converts a multi-byte string from @var{str} to its wide character
representation, replacing each run of one or more whitespace characters
with a single space character (ASCII 32).

The result is returned in @var{retptr}.  It is allocated using @code{malloc}(3).

Returns 0 on success.  On error, returns -1 and sets @code{errno} to
one of the following values:

@table @asis
@item ENOMEM
Not enough memory to allocate the return buffer.

@item EILSEQ
An invalid wide character is encountered.
@end table
@end deftypefn

@node Comparing UTF-8 strings
@subsection Comparing UTF-8 strings

@deftypefn Function int utf8_symcmp (unsigned char *@var{a}, @
  unsigned char *@var{b})
Compares first UTF-8 characters from @var{a} and @var{b}.
@end deftypefn

@deftypefn Function int utf8_symcasecmp (unsigned char *@var{a}, @
  unsigned char *@var{b})
Compares first UTF-8 characters from @var{a} and @var{b}, ignoring the
case.
@end deftypefn
  
@deftypefn Function int utf8_strcasecmp (unsigned char *@var{a}, @
  unsigned char *@var{b})
Compares the two UTF-8 strings @var{a} and @var{b}, ignoring the case
of the characters.  
@end deftypefn
  
@deftypefn Function int utf8_strncasecmp (unsigned char *@var{a}, @
  unsigned char *@var{b}, size_t @var{maxlen})
Compares at most @var{maxlen} first characters from the two UTF-8
strings @var{a} and @var{b}, ignoring the case of the characters.   
@end deftypefn

@deftypefn Function int utf8_wc_strcmp (const unsigned *@var{a}, @
  const unsigned *@var{b})
Compare the two wide character strings @var{a} and @var{b}.
@end deftypefn

@deftypefn Function int utf8_wc_strncmp (const unsigned *@var{a}, @
 const unsigned *@var{b}, size_t @var{n})
Compares at most @var{n} first characters from the wide character
strings @var{a} and @var{b}.
@end deftypefn

@deftypefn Function int utf8_wc_strcasecmp (const unsigned *@var{a}, const unsigned *@var{b})
Compares the two wide character strings @var{a} and @var{b}, ignoring the case
of the characters.
@end deftypefn

@deftypefn Function int utf8_wc_strncasecmp (const unsigned *@var{a},@
  const unsigned *@var{b}, size_t @var{n})
Compares at most first @var{n} characters of the two wide character
strings @var{a} and @var{b}, ignoring the case.
@end deftypefn

@node Character lookups
@subsection Character lookups

@deftypefn Function {unsigned *} utf8_wc_strchr (const unsigned *@var{str},@
  unsigned @var{chr})
Returns a pointer to the first occurrence of wide character @var{chr} in
string @var{str}, or @samp{NULL}, if no such character is encountered.
@end deftypefn

@deftypefn Function {unsigned *} utf8_wc_strchr_ci (const unsigned *@var{str},@
  unsigned @var{chr})
Returns a pointer to the first occurrence of wide character @var{chr}
(case-insensitive) in string @var{str}, or @samp{NULL}, if no such
character is encountered.
@end deftypefn

@deftypefn Function {const unsigned *} utf8_wc_strstr (const unsigned *var{text},@
  const unsigned *@var{pattern})
Finds the first occurrence of @var{pattern} in @var{text}.  Returns a
pointer to the beginning of pattern in @var{text}.  Returns
@code{NULL} if no occurrence was found.
@end deftypefn

@node Functions for converting UTF-8 characters
@subsection Functions for converting UTF-8 characters

@deftypefn Function unsigned utf8_wc_toupper (unsigned @var{wc})
Converts wide character @var{wc} to upper case, if possible.  Returns
@var{wc}, if it cannot be converted.
@end deftypefn

@deftypefn Function int utf8_toupper (char *@var{s}, size_t @var{len})
Converts first @var{len} bytes of the UTF-8 string @var{s} to upper
case, if possible.
@end deftypefn

@deftypefn Function unsigned utf8_wc_tolower (unsigned @var{wc})
Converts wide character @var{wc} to lower case, if possible.  Returns
@var{wc}, if it cannot be converted.
@end deftypefn

@deftypefn Function int utf8_tolower (char *@var{s}, size_t @var{len})
Converts first @var{len} bytes of the UTF-8 string @var{s} to lower
case, if possible.
@end deftypefn

@deftypefn Function void utf8_wc_strupper (unsigned *@var{str})
Converts each character from the wide character string @var{str} to
uppercase, if applicable.
@end deftypefn

@deftypefn Function void utf8_wc_strlower (unsigned *@var{str})
Converts each character from the wide character string @var{str} to
lowercase, if applicable.
@end deftypefn

@node Additional functions
@subsection Additional functions

@deftypefn Function {unsigned *} utf8_wc_strdup (const unsigned *@var{s})
Returns a pointer to a new wide character string which is a duplicate
of the string @var{s}.  Memory for the new string is obtained with 
@code{malloc}(3), and can be freed with @code{free}(3).
@end deftypefn

@deftypefn Function {unsigned *} utf8_wc_quote (const unsigned *@var{s})
Quotes occurrences of backslash and double-quote in @var{s} by
prefixing each of them with a backslash.  The return value is
allocated using @code{malloc}(3).
@end deftypefn

@deftypefn Function int utf8_quote (const char *@var{str}, char **@var{sptr})
Quotes occurrences of backslash and double-quote in @var{s} by
prefixing each of them with a backslash.  On success stores the result
(allocated with @code{malloc}(3)) in @var{sptr}, and returns 0.  On
error, returns -1 and sets @code{errno} to the one of the following:

@table @asis
@item ENOMEM
Not enough memory to allocate the return buffer.

@item EILSEQ
An invalid wide character is encountered.
@end table
@end deftypefn

@deftypefn Function size_t utf8_wc_hash_string (const unsigned *@var{ws}, @
  size_t @var{n})
Compute a hash code of @var{ws} for a symbol table of @var{n} buckets.
@end deftypefn
  
@deftypefn Function int dico_levenshtein_distance (const char *@var{a}, @
  const char *@var{b}, int @var{flags})
Computes Levenshtein distance between UTF-8 strings @var{a} and
@var{b}.  The @var{flags} argument is a bitwise or of one or more
flags:

@table @code
@item 0
Default - compute Levenstein distance, treating both arguments
literally.
@item DICO_LEV_NORM
Treat runs of one or more whitespace characters as a single 
space character (ASCII 32).
@item DICO_LEV_DAMERAU
Compute Damerau-Levenshtein distance.  This distance takes into
account transpositions.
@end table
@end deftypefn
  
@deftypefn Function int dico_soundex (const char *@var{word}, @
  char @var{code}[DICO_SOUNDEX_SIZE])
Computes the @acronym{Soundex} code for the given @var{word}.  The
code is stored in @var{code}.  Returns 0 on success, -1 if @var{word}
is not a valid UTF-8 string.

@defvr Define DICO_SOUNDEX_SIZE
This macro definition expands to the size of @acronym{Soundex} code
buffer, including the terminal zero.
@end defvr

Note that this function silently ignores all characters, except Latin
letters.
@end deftypefn

@node util
@section util
@UNREVISED

@deftypefn Function {char *} dico_full_file_name (const char *@var{dir}, @
  const char *@var{file})
@end deftypefn
  
@deftypefn Function size_t dico_trim_nl (char *@var{buf})
@end deftypefn

@deftypefn Function size_t dico_trim_ws (char *@var{buf})
@end deftypefn

@node xlat
@section xlat
@UNREVISED

@deftp struct xlat_tab
@smallexample
struct xlat_tab @{
    char *string;
    int num;
@};
@end smallexample
@end deftp

@deftypefn Function int xlat_string (struct xlat_tab *@var{tab}, @
  const char *@var{string}, size_t @var{len}, @
  int @var{flags}, int *@var{result})
@deftypefnx Function int xlat_c_string (struct xlat_tab *@var{tab}, @
  const char *@var{string}, @
  int @var{flags}, int *@var{result})

@table @code
@item XLAT_ICASE
@end table

@end deftypefn