TextCollection.h

   1 /******************************************************************************
   2  *   Copyright (C) 2008 by Niko Valimaki <nvalimak@cs.helsinki.fi>            *
   3  *   Text collection interface for an in-memory XQuery/XPath engine           *
   4  *                                                                            *
   5  *   This program is free software; you can redistribute it and/or modify     *
   6  *   it under the terms of the GNU Lesser General Public License as published *
   7  *   by the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                      *
   9  *                                                                            *
  10  *   This program is distributed in the hope that it will be useful,          *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of           *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            *
  13  *   GNU Lesser General Public License for more details.                      *
  14  *                                                                            *
  15  *   You should have received a copy of the GNU Lesser General Public License *
  16  *   along with this program; if not, write to the                            *
  17  *   Free Software Foundation, Inc.,                                          *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.                *
  19  ******************************************************************************/
  20
  21 #ifndef _SXSI_TextCollection_h_
  22 #define _SXSI_TextCollection_h_
  23
  24 #include "Tools.h" // Defines ulong and uchar.
  25 #include <vector>
  26 #include <utility> // Defines std::pair.
  27
  28 // Default samplerate for suffix array samples
  29 #define TEXTCOLLECTION_DEFAULT_SAMPLERATE 64
  30
  31 namespace SXSI
  32 {
  33     /**
  34      * General interface for a text collection
  35      *
  36      * Class is virtual, make objects by calling
  37      * the static method InitTextCollection().
  38      */
  39     class TextCollection
  40     {
  41     public:
  42         // Type of document identifier
  43         typedef int DocId;
  44         // Type for text position (FIXME ulong or long?)
  45         typedef ulong TextPosition;
  46
  47         /**
  48          * Init an instance of a text collection object
  49          *
  50          * Returns a pointer to an object implementing this interface.
  51          */
  52         static TextCollection * InitTextCollection(unsigned samplerate = TEXTCOLLECTION_DEFAULT_SAMPLERATE);
  53         /**
  54          * Load from a file
  55          *
  56          * New samplerate can be given, otherwise will use the one specified in the save file!
  57          * Note: This is not a static method; call InitTextCollection() first to get the object handle.
  58          *
  59          * Throws an exception if std::fread() fails.
  60          *
  61          */
  62         virtual void Load(FILE *, unsigned samplerate = 0) = 0;
  63         /**
  64          * Save data structure into a file
  65          *
  66          * Throws an exception if std::fwrite() fails.
  67          */
  68         virtual void Save(FILE *) const = 0;
  69         /**
  70          * Virtual destructor
  71          */
  72         virtual ~TextCollection() { };
  73         /**
  74          * Insert text
  75          *
  76          * Must be a zero-terminated string from alphabet [1,255].
  77          * Can not be called after makeStatic().
  78          * The i'th text insertion gets an identifier value i-1.
  79          * In other words, document identifiers start from 0.
  80          */
  81         virtual void InsertText(uchar const *) = 0;
  82         /**
  83          * Make static
  84          *
  85          * Convert to a static collection; reduces space and time complexities.
  86          * New texts can not be inserted after this operation.
  87          */
  88         virtual void MakeStatic() = 0;
  89
  90         /**
  91            tests if the string pointed to by DocId is empty
  92          */
  93
  94         virtual bool EmptyText(DocId) const = 0;
  95
  96         /**
  97          * Displaying content
  98          *
  99          * Returns the i'th text in the collection.
 100          * The numbering starts from 0.
 101          */
 102         virtual uchar* GetText(DocId) const = 0;
 103         /**
 104          * Returns substring [i, j] of k'th text
 105          *
 106          * Note: Parameters i and j are text positions inside the k'th text.
 107          */
 108 //        virtual uchar* GetText(DocId, TextPosition, TextPosition) const = 0;
 109         /**
 110          * Returns backwards (reverse) iterator to the end of i'th text
 111          *
 112          * Note: Do we need this?
 113          * Forward iterator would be really in-efficient compared to
 114          * getText(k).
 115          *
 116          * TODO Define and implement const_reverse_iterator.
 117          */
 118         //const_reverse_iterator rend(DocId) const;
 119
 120         /**
 121          * Existential queries
 122          */
 123         // Is there a text prefixed by given string?
 124         virtual bool IsPrefix(uchar const *) const = 0;
 125         // Is there a text having given string as a suffix?
 126         virtual bool IsSuffix(uchar const *) const = 0;
 127         // Is there a text that equals given string?
 128         virtual bool IsEqual(uchar const *) const = 0;
 129         // Does a text contain given string?
 130         virtual bool IsContains(uchar const *) const = 0;
 131         // Is there a text that is lexicographically less than given string?
 132         virtual bool IsLessThan(uchar const *) const = 0;
 133
 134         /**
 135          * Counting queries
 136          * Result is the number of occurrences.
 137          */
 138         virtual ulong Count(uchar const *) const = 0;
 139         /**
 140          * More counting queries
 141          * Result is the number of documents.
 142          */
 143         virtual unsigned CountPrefix(uchar const *) const = 0;
 144         virtual unsigned CountSuffix(uchar const *) const = 0;
 145         virtual unsigned CountEqual(uchar const *) const = 0;
 146         virtual unsigned CountContains(uchar const *) const = 0;
 147         virtual unsigned CountLessThan(uchar const *) const = 0;
 148
 149         /**
 150          * Document reporting queries
 151          *
 152          * Result is a vector of document id's in some undefined order.
 153          */
 154         // Data type for results
 155         typedef std::vector<DocId> document_result;
 156         virtual document_result Prefix(uchar const *) const = 0;
 157         virtual document_result Suffix(uchar const *) const = 0;
 158         virtual document_result Equal(uchar const *) const = 0;
 159         virtual document_result Contains(uchar const *) const = 0;
 160         virtual document_result LessThan(uchar const *) const = 0;
 161
 162         /**
 163          * Full reporting queries
 164          *
 165          * Result is a vector of pairs <doc id, offset> in some undefined order.
 166          */
 167         // Data type for results
 168         typedef std::vector<std::pair<DocId, TextPosition> > full_result;
 169         virtual full_result FullContains(uchar const *) const = 0;
 170
 171     protected:
 172         // Protected constructor; call the static function InitTextCollection().
 173         TextCollection() { };
 174
 175         // No copy constructor or assignment
 176         TextCollection(TextCollection const&);
 177         TextCollection& operator = (TextCollection const&);
 178     };
 179 }
 180 #endif