swcsa/interface.h

   1
   2 /* General interface for using the compressed index libraries */
   3
   4 #ifndef uchar
   5 #define uchar unsigned char
   6 #endif
   7 #ifndef uint
   8 #define uint  unsigned int
   9 #endif
  10 #ifndef ulong
  11 #define ulong unsigned long
  12 #endif
  13
  14 /* Error management */
  15
  16         /* Returns a string describing the error associated with error number
  17           e. The string must not be freed, and it will be overwritten with
  18           subsequent calls. */
  19
  20 char *error_index (int e);
  21
  22 /* Building the index */
  23
  24         /* Creates index from text[0..length-1]. Note that the index is an
  25           opaque data type. Any build option must be passed in string
  26           build_options, whose syntax depends on the index. The index must
  27           always work with some default parameters if build_options is NULL.
  28           The returned index is ready to be queried. */
  29
  30 int build_index (uchar *text, ulong length, char *build_options, void **index);
  31
  32         /*  Saves index on disk by using single or multiple files, having
  33           proper extensions. */
  34
  35 int save_index (void *index, char *filename);
  36
  37         /*  Loads index from one or more file(s) named filename, possibly
  38           adding the proper extensions. */
  39
  40 int load_index (char *filename, void **index);
  41
  42         /* Frees the memory occupied by index. */
  43
  44 int free_index (void *index);
  45
  46         /* Gives the memory occupied by index in bytes. */
  47
  48 int index_size(void *index, ulong *size);
  49
  50 /* Querying the index */
  51
  52         /* Writes in numocc the number of occurrences of the substring
  53           pattern[0..length-1] found in the text indexed by index. */
  54
  55 //int count (void *index, uchar *pattern, ulong length, ulong *numocc);
  56 //
  57 //        /* Writes in numocc the number of occurrences of the substring
  58 //          pattern[0..length-1] in the text indexed by index. It also allocates
  59 //          occ (which must be freed by the caller) and writes the locations of
  60 //          the numocc occurrences in occ, in arbitrary order.  */
  61 //
  62 //int locate (void *index, uchar *pattern, ulong length, ulong **occ,
  63 //        ulong *numocc);
  64 //
  65 //        /* Gives the length of the text indexed */
  66 //
  67 //int get_length(void *index, ulong *length);
  68 //
  69 ///* Accessing the indexed text  */
  70 //
  71 //        /*  Allocates snippet (which must be freed by the caller) and writes
  72 //          the substring text[from..to] into it. Returns in snippet_length the
  73 //          length of the text snippet actually extracted (that could be less
  74 //          than to-from+1 if to is larger than the text size). */
  75 //
  76 //int extract (void *index, ulong from, ulong to, uchar **snippet,
  77 //        ulong *snippet_length);
  78 //
  79 //        /* Displays the text (snippet) surrounding any occurrence of the
  80 //          substring pattern[0..length-1] within the text indexed by index.
  81 //          The snippet must include numc characters before and after the
  82 //          pattern occurrence, totalizing length+2*numc characters, or less if
  83 //          the text boundaries are reached. Writes in numocc the number of
  84 //          occurrences, and allocates the arrays snippet_text and
  85 //          snippet_lengths (which must be freed by the caller). The first is a
  86 //          character array of numocc*(length+2*numc) characters, with a new
  87 //          snippet starting at every multiple of length+2*numc. The second
  88 //          gives the real length of each of the numocc snippets. */
  89 //
  90 //int display (void *index, uchar *pattern, ulong length, ulong numc,
  91 //        ulong *numocc, uchar **snippet_text, ulong **snippet_lengths);
  92
  93         /*  Obtains the length of the text indexed by index. */
  94
  95 int length (void *index, ulong *length);
  96