src/storage/ngram.h

   1 /*
   2  *  libpinyin
   3  *  Library to deal with pinyin.
   4  *
   5  *  Copyright (C) 2006-2007 Peng Wu
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License as published by
   9  *  the Free Software Foundation; either version 2 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  This program is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15  *  GNU General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU General Public License
  18  *  along with this program; if not, write to the Free Software
  19  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  20  */
  21
  22 #ifndef NGRAM_H
  23 #define NGRAM_H
  24
  25 #include <db.h>
  26
  27 namespace pinyin{
  28
  29 class Bigram;
  30
  31 /** Note:
  32  *  The system single gram contains the trained freqs.
  33  *  The user single gram contains the delta freqs.
  34  *  During the Viterbi beam search, use merge_single_gram to merge the system
  35  *    single gram and the user single gram.
  36  */
  37
  38
  39 /**
  40  * SingleGram:
  41  *
  42  * The single gram in the bi-gram.
  43  *
  44  */
  45 class SingleGram{
  46     friend class Bigram;
  47     friend bool merge_single_gram(SingleGram * merged,
  48                                   const SingleGram * system,
  49                                   const SingleGram * user);
  50
  51 private:
  52     MemoryChunk m_chunk;
  53     SingleGram(void * buffer, size_t length);
  54 public:
  55     /**
  56      * SingleGram::SingleGram:
  57      *
  58      * The constructor of the SingleGram.
  59      *
  60      */
  61     SingleGram();
  62     /**
  63      * SingleGram::retrieve_all:
  64      * @array: the GArray to store the retrieved bi-gram phrase item.
  65      * @returns: whether the retrieve operation is successful.
  66      *
  67      * Retrieve all bi-gram phrase items in this single gram.
  68      *
  69      */
  70     bool retrieve_all(/* out */ BigramPhraseWithCountArray array) const;
  71
  72     /**
  73      * SingleGram::search:
  74      * @range: the token range.
  75      * @array: the GArray to store the matched bi-gram phrase item.
  76      * @returns: whether the search operation is successful.
  77      *
  78      * Search the bi-gram phrase items according to the token range.
  79      *
  80      * Note: the array result may contain many items.
  81      *
  82      */
  83     bool search(/* in */ PhraseIndexRange * range,
  84                /* out */ BigramPhraseArray array) const;
  85
  86     /**
  87      * SingleGram::insert_freq:
  88      * @token: the phrase token.
  89      * @freq: the freq of this token.
  90      * @returns: whether the insert operation is successful.
  91      *
  92      * Insert the token with the freq.
  93      *
  94      */
  95     bool insert_freq(/* in */ phrase_token_t token,
  96                      /* in */ guint32 freq);
  97
  98     /**
  99      * SingleGram::remove_freq:
 100      * @token: the phrase token.
 101      * @freq: the freq of the removed token.
 102      * @returns: whether the remove operation is successful.
 103      *
 104      * Remove the token.
 105      *
 106      */
 107     bool remove_freq(/* in */ phrase_token_t token,
 108                      /* out */ guint32 & freq);
 109
 110     /**
 111      * SingleGram::get_freq:
 112      * @token: the phrase token.
 113      * @freq: the freq of the token.
 114      * @returns: whether the get operation is successful.
 115      *
 116      * Get the freq of the token.
 117      *
 118      */
 119     bool get_freq(/* in */ phrase_token_t token,
 120                /* out */ guint32 & freq) const;
 121
 122     /**
 123      * SingleGram::set_freq:
 124      * @token: the phrase token.
 125      * @freq: the freq of the token.
 126      * @returns: whether the set operation is successful.
 127      *
 128      * Set the freq of the token.
 129      *
 130      */
 131     bool set_freq(/* in */ phrase_token_t token,
 132                   /* in */ guint32 freq);
 133
 134     /**
 135      * SingleGram::get_total_freq:
 136      * @total: the total freq of this single gram.
 137      * @returns: whether the get operation is successful.
 138      *
 139      * Get the total freq of this single gram.
 140      *
 141      */
 142     bool get_total_freq(guint32 & total) const;
 143
 144     /**
 145      * SingleGram::set_total_freq:
 146      * @total: the total freq of this single gram.
 147      * @returns: whether the set operation is successful.
 148      *
 149      * Set the total freq of this single gram.
 150      *
 151      */
 152     bool set_total_freq(guint32 total);
 153
 154     /**
 155      * SingleGram::get_length:
 156      * @returns: the number of items in this single gram.
 157      *
 158      * Get the number of items in this single gram.
 159      *
 160      */
 161     guint32 get_length();
 162
 163     /**
 164      * SingleGram::mask_out:
 165      * @mask: the mask.
 166      * @value: the value.
 167      * @returns: the number of removed items.
 168      *
 169      * Mask out the matched items in this single gram.
 170      *
 171      */
 172     guint32 mask_out(phrase_token_t mask, phrase_token_t value);
 173
 174     /**
 175      * SingleGram::prune:
 176      * @returns: whether the prune operation is successful.
 177      *
 178      * Obsoleted by Katz k mixture model pruning.
 179      *
 180      */
 181     bool prune();
 182 };
 183
 184
 185 /**
 186  * Bigram:
 187  *
 188  * The Bi-gram class.
 189  *
 190  */
 191 class Bigram{
 192 private:
 193     DB * m_db;
 194
 195     void reset(){
 196         if ( m_db ){
 197         m_db->sync(m_db, 0);
 198             m_db->close(m_db, 0);
 199             m_db = NULL;
 200         }
 201     }
 202
 203 public:
 204     /**
 205      * Bigram::Bigram:
 206      *
 207      * The constructor of the Bigram.
 208      *
 209      */
 210     Bigram(){
 211         m_db = NULL;
 212     }
 213
 214     /**
 215      * Bigram::~Bigram:
 216      *
 217      * The destructor of the Bigram.
 218      *
 219      */
 220     ~Bigram(){
 221         reset();
 222     }
 223
 224     /**
 225      * Bigram::load_db:
 226      * @dbfile: the Berkeley DB file name.
 227      * @returns: whether the load operation is successful.
 228      *
 229      * Load the Berkeley DB into memory.
 230      *
 231      */
 232     bool load_db(const char * dbfile);
 233
 234     /**
 235      * Bigram::save_db:
 236      * @dbfile: the Berkeley DB file name.
 237      * @returns: whether the save operation is successful.
 238      *
 239      * Save the in-memory Berkeley DB into disk.
 240      *
 241      */
 242     bool save_db(const char * dbfile);
 243
 244     /**
 245      * Bigram::attach:
 246      * @dbfile: the Berkeley DB file name.
 247      * @flags: the flags of enum ATTACH_FLAG.
 248      * @returns: whether the attach operation is successful.
 249      *
 250      * Attach this Bigram with the Berkeley DB.
 251      *
 252      */
 253     bool attach(const char * dbfile, guint32 flags);
 254
 255     /**
 256      * Bigram::load:
 257      * @index: the previous token in the bi-gram.
 258      * @single_gram: the single gram of the previous token.
 259      * @returns: whether the load operation is successful.
 260      *
 261      * Load the single gram of the previous token.
 262      *
 263      */
 264     bool load(/* in */ phrase_token_t index,
 265               /* out */ SingleGram * & single_gram);
 266
 267     /**
 268      * Bigram::store:
 269      * @index: the previous token in the bi-gram.
 270      * @single_gram: the single gram of the previous token.
 271      * @returns: whether the store operation is successful.
 272      *
 273      * Store the single gram of the previous token.
 274      *
 275      */
 276     bool store(/* in */ phrase_token_t index,
 277                /* in */ SingleGram * single_gram);
 278
 279     /**
 280      * Bigram::remove:
 281      * @index: the previous token in the bi-gram.
 282      * @returns: whether the remove operation is successful.
 283      *
 284      * Remove the single gram of the previous token.
 285      *
 286      */
 287     bool remove(/* in */ phrase_token_t index);
 288
 289     /**
 290      * Bigram::get_all_items:
 291      * @items: the GArray to store all previous tokens.
 292      * @returns: whether the get operation is successful.
 293      *
 294      * Get the array of all previous tokens for parameter estimation.
 295      *
 296      */
 297     bool get_all_items(/* out */ GArray * items);
 298
 299     /**
 300      * Bigram::mask_out:
 301      * @mask: the mask.
 302      * @value: the value.
 303      * @returns: whether the mask out operation is successful.
 304      *
 305      * Mask out the matched items.
 306      *
 307      */
 308     bool mask_out(phrase_token_t mask, phrase_token_t value);
 309 };
 310
 311 /**
 312  * merge_single_gram:
 313  * @merged: the merged single gram of system and user single gram.
 314  * @system: the system single gram to be merged.
 315  * @user: the user single gram to be merged.
 316  * @returns: whether the merge operation is successful.
 317  *
 318  * Merge the system and user single gram into one merged single gram.
 319  *
 320  * Note: Please keep system and user single gram
 321  * when using merged single gram.
 322  *
 323  */
 324 bool merge_single_gram(SingleGram * merged, const SingleGram * system,
 325                        const SingleGram * user);
 326
 327 };
 328
 329 #endif