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     /**
  35      * General interface for a text collection
  36      *
  37      * Class is virtual, make objects by calling
  38      * the static method InitTextCollection().
  39      */
  40     class TextCollection
  41     {
  42     public:
  43         // Type of document identifier
  44         typedef int DocId;
  45         // Type for text position (FIXME ulong or long?)
  46         typedef ulong TextPosition;
  47
  48         /**
  49          * Load from a file
  50          *
  51          * New samplerate can be given, otherwise will use the one specified in the save file!
  52          * Note: This is not a static method; call InitTextCollection() first to get the object handle.
  53          *
  54          * Throws an exception if std::fread() fails.
  55          *
  56          */
  57         static TextCollection* Load(FILE *, unsigned samplerate = 0);
  58
  59         /**
  60          * Save data structure into a file
  61          *
  62          * Throws an exception if std::fwrite() fails.
  63          */
  64         virtual void Save(FILE *) const = 0;
  65
  66         /**
  67          * Virtual destructor
  68          */
  69         virtual ~TextCollection() { };
  70
  71         /**
  72          * Tests if the string pointed to by DocId is empty
  73          */
  74         virtual bool EmptyText(DocId) const = 0;
  75
  76         /**
  77          * Displaying content
  78          *
  79          * Returns the i'th text in the collection.
  80          * The numbering starts from 0.
  81          */
  82         virtual uchar* GetText(DocId) const = 0;
  83         /**
  84          * Returns substring [i, j] of k'th text
  85          *
  86          * Note: Parameters i and j are text positions inside the k'th text.
  87          */
  88 //        virtual uchar* GetText(DocId, TextPosition, TextPosition) const = 0;
  89         /**
  90          * Returns backwards (reverse) iterator to the end of i'th text
  91          *
  92          * Note: Do we need this?
  93          * Forward iterator would be really in-efficient compared to
  94          * getText(k).
  95          *
  96          * TODO Define and implement const_reverse_iterator.
  97          */
  98         //const_reverse_iterator rend(DocId) const;
  99
 100         /**
 101          * Existential queries
 102          */
 103         // Is there a text prefixed by given string?
 104         virtual bool IsPrefix(uchar const *) const = 0;
 105         // Is there a text having given string as a suffix?
 106         virtual bool IsSuffix(uchar const *) const = 0;
 107         // Is there a text that equals given string?
 108         virtual bool IsEqual(uchar const *) const = 0;
 109         // Does a text contain given string?
 110         virtual bool IsContains(uchar const *) const = 0;
 111         // Is there a text that is lexicographically less than given string?
 112         virtual bool IsLessThan(uchar const *) const = 0;
 113
 114         /**
 115          * Existential queries for given DocId interval.
 116          */
 117         virtual bool IsPrefix(uchar const *, DocId, DocId) const = 0;
 118         virtual bool IsSuffix(uchar const *, DocId, DocId) const = 0;
 119         virtual bool IsEqual(uchar const *, DocId, DocId) const = 0;
 120         virtual bool IsContains(uchar const *, DocId, DocId) const = 0;
 121         virtual bool IsLessThan(uchar const *, DocId, DocId) const = 0;
 122
 123         /**
 124          * Counting queries
 125          * Result is the number of occurrences.
 126          */
 127         virtual ulong Count(uchar const *) const = 0;
 128         /**
 129          * More counting queries
 130          * Result is the number of documents.
 131          */
 132         virtual unsigned CountPrefix(uchar const *) const = 0;
 133         virtual unsigned CountSuffix(uchar const *) const = 0;
 134         virtual unsigned CountEqual(uchar const *) const = 0;
 135         virtual unsigned CountContains(uchar const *) const = 0;
 136         virtual unsigned CountLessThan(uchar const *) const = 0;
 137
 138         /**
 139          * Counting queries for given DocId interval
 140          */
 141         virtual unsigned CountPrefix(uchar const *, DocId, DocId) const = 0;
 142         virtual unsigned CountSuffix(uchar const *, DocId, DocId) const = 0;
 143         virtual unsigned CountEqual(uchar const *, DocId, DocId) const = 0;
 144         virtual unsigned CountContains(uchar const *, DocId, DocId) const = 0;
 145         virtual unsigned CountLessThan(uchar const *, DocId, DocId) const = 0;
 146
 147         /**
 148          * Document reporting queries
 149          *
 150          * Result is a vector of document id's in some undefined order.
 151          */
 152         // Data type for results
 153         typedef std::vector<DocId> document_result;
 154         virtual document_result Prefix(uchar const *) const = 0;
 155         virtual document_result Suffix(uchar const *) const = 0;
 156         virtual document_result Equal(uchar const *) const = 0;
 157         virtual document_result Contains(uchar const *) const = 0;
 158         virtual document_result LessThan(uchar const *) const = 0;
 159
 160         /**
 161          * Document reporting queries for given DocId interval.
 162          */
 163         virtual document_result Prefix(uchar const *, DocId, DocId) const = 0;
 164         virtual document_result Suffix(uchar const *, DocId, DocId) const = 0;
 165         virtual document_result Equal(uchar const *, DocId, DocId) const = 0;
 166         virtual document_result Contains(uchar const *, DocId, DocId) const = 0;
 167         virtual document_result LessThan(uchar const *, DocId, DocId) const = 0;
 168
 169         /**
 170          * Full reporting queries
 171          *
 172          * Result is a vector of pairs <doc id, offset> in some undefined order.
 173          */
 174         // Data type for results
 175         typedef std::vector<std::pair<DocId, TextPosition> > full_result;
 176         virtual full_result FullContains(uchar const *) const = 0;
 177         // Full reporting query for given DocId interval
 178         virtual full_result FullContains(uchar const *, DocId, DocId) const = 0;
 179
 180     protected:
 181         // Protected constructor; use TextCollectionBuilder
 182         TextCollection() { };
 183
 184         // No copy constructor or assignment
 185         TextCollection(TextCollection const&);
 186         TextCollection& operator = (TextCollection const&);
 187     };
 188 }
 189 #endif