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::prune:
 156      * @returns: whether the prune operation is successful.
 157      *
 158      * Obsoleted by Katz k mixture model pruning.
 159      *
 160      */
 161     bool prune();
 162 };
 163
 164
 165 /**
 166  * Bigram:
 167  *
 168  * The Bi-gram class.
 169  *
 170  */
 171 class Bigram{
 172 private:
 173     DB * m_db;
 174
 175     void reset(){
 176         if ( m_db ){
 177         m_db->sync(m_db, 0);
 178             m_db->close(m_db, 0);
 179             m_db = NULL;
 180         }
 181     }
 182
 183 public:
 184     /**
 185      * Bigram::Bigram:
 186      *
 187      * The constructor of the Bigram.
 188      *
 189      */
 190     Bigram(){
 191         m_db = NULL;
 192     }
 193
 194     /**
 195      * Bigram::~Bigram:
 196      *
 197      * The destructor of the Bigram.
 198      *
 199      */
 200     ~Bigram(){
 201         reset();
 202     }
 203
 204     /**
 205      * Bigram::load_db:
 206      * @dbfile: the Berkeley DB file name.
 207      * @returns: whether the load operation is successful.
 208      *
 209      * Load the Berkeley DB into memory.
 210      *
 211      */
 212     bool load_db(const char * dbfile);
 213
 214     /**
 215      * Bigram::save_db:
 216      * @dbfile: the Berkeley DB file name.
 217      * @returns: whether the save operation is successful.
 218      *
 219      * Save the in-memory Berkeley DB into disk.
 220      *
 221      */
 222     bool save_db(const char * dbfile);
 223
 224     /**
 225      * Bigram::attach:
 226      * @dbfile: the Berkeley DB file name.
 227      * @flags: the flags of enum ATTACH_FLAG.
 228      * @returns: whether the attach operation is successful.
 229      *
 230      * Attach this Bigram with the Berkeley DB.
 231      *
 232      */
 233     bool attach(const char * dbfile, guint32 flags);
 234
 235     /**
 236      * Bigram::load:
 237      * @index: the previous token in the bi-gram.
 238      * @single_gram: the single gram of the previous token.
 239      * @returns: whether the load operation is successful.
 240      *
 241      * Load the single gram of the previous token into the SingleGram class.
 242      *
 243      */
 244     bool load(/* in */ phrase_token_t index,
 245               /* out */ SingleGram * & single_gram);
 246
 247     /**
 248      * Bigram::store:
 249      * @index: the previous token in the bi-gram.
 250      * @single_gram: the single gram of the previous token.
 251      * @returns: whether the store operation is successful.
 252      *
 253      * Store the single gram of the previous token from the SingleGram class.
 254      *
 255      */
 256     bool store(/* in */ phrase_token_t index,
 257                /* in */ SingleGram * single_gram);
 258
 259     /**
 260      * Bigram::get_all_items:
 261      * @items: the GArray to store all previous tokens.
 262      * @returns: whether the get operation is successful.
 263      *
 264      * Get the array of all previous tokens for parameter estimation.
 265      *
 266      */
 267     bool get_all_items(/* out */ GArray * items);
 268 };
 269
 270 /**
 271  * merge_single_gram:
 272  * @merged: the merged single gram of system and user single gram.
 273  * @system: the system single gram to be merged.
 274  * @user: the user single gram to be merged.
 275  * @returns: whether the merge operation is successful.
 276  *
 277  * Merge the system and user single gram into one merged single gram.
 278  *
 279  * Note: Please keep system and user single gram
 280  * when using merged single gram.
 281  *
 282  */
 283 bool merge_single_gram(SingleGram * merged, const SingleGram * system,
 284                        const SingleGram * user);
 285
 286 };
 287
 288 #endif