src/core/WordList.h

   1 /**
   2  * FileName: WordList.h
   3  * Used to define the class WordList which is used to creat a circular
   4  * reviewing system for the user, and help them recite something quickly.
   5  *
   6  * Copyright (C) 2008 Kermit Mei <kermit.mei@gmail.com>
   7  * All Rights Reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License version 3 as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation.
  21  *
  22  * Written by Kermit Mei <kermit.mei@gmail.com>
  23  *
  24  * Many of the ideas implemented here are from the author's experiment.
  25  * But the dictionary's format coincide with the other word recite software
  26  * to help the users get more available data. And the review times designed
  27  * by means of the theory named Forgetting Curve which dicoveried by the
  28  * German psychologist named Hermann Ebbinghaus(1850–1909).
  29  *
  30  **/
  31
  32 #ifndef WORDLIST_H
  33 #define WORDLIST_H
  34
  35 namespace freeRecite {
  36
  37 /**
  38  * To use this class you should put something in an Random Accessing
  39  * Container such as std::vector or an array.
  40  **/
  41
  42 class WordList
  43 {
  44 public:
  45   //Initialize WordList using the size of the container object.
  46   WordList(size_t initSize = 0, const std::vector<unsigned> *initPt = 0);
  47
  48   //Destroy WordList.
  49   ~WordList();
  50
  51   //Return the size of word list, put it here to make it inline.
  52   unsigned size() const;
  53
  54   //Return r_times;
  55   int times() const;
  56
  57   //Detect whether it is valid.
  58   bool isValid() const;
  59
  60   /**
  61    * Get the Next word's index.
  62    * Note: It's undefined to call this method on an unvalid object.
  63    *       So you must always call isValid() before using it.
  64    **/
  65   unsigned getNext() const;
  66
  67   //Get the first word's status.
  68   int status() const;
  69
  70   /**
  71    * If the input word is true, then you must call pass().
  72    * This method will updata the WordList to help you get
  73    * the correct index of the next word, when you call
  74    * getNext() next time.:P
  75    * If it return 0, then the word is tested first.
  76    **/
  77   void pass();
  78
  79   /**
  80    * If the input word is false, then you must call lose().
  81    * The return value is the status of the current word.
  82    **/
  83   void lose();
  84
  85   /**
  86    * After you add one word to the contain, you must call
  87    * this method to synchronize the the contain withe the list.
  88    * The argument 'size' is the size of the new contain.
  89    **/
  90   void add();
  91
  92   /**
  93    * After you remove one word from the contain, you must call
  94    * this method to synchronize the the contain withe the list.
  95    * The argument 'size' is the size of the new contain.
  96    **/
  97   void remove();
  98
  99 private:
 100
 101   //Move the first element one afterward, advance all the pointers
 102   void moveAfter(unsigned i);
 103
 104   //The element is passed, remove it form the WordList;
 105   void pop();
 106
 107   struct NodeWord
 108   {
 109     NodeWord(unsigned initValue)
 110       :index(initValue),status(0),next(0)
 111     { /* Do Nothing Here! */ }
 112     unsigned index;
 113     unsigned status;
 114     NodeWord *next;
 115   };
 116
 117   unsigned __size;
 118   unsigned __maxIndex;
 119   const std::vector<unsigned> *posToStatus;
 120   int r_times;
 121   NodeWord *first;
 122   NodeWord *last;
 123 };
 124
 125 inline
 126 unsigned WordList::size() const {
 127   return __size;
 128 }
 129
 130 inline
 131 int WordList::times() const {
 132   return r_times;
 133 }
 134
 135 inline
 136 unsigned WordList::getNext() const {
 137   return first->index;
 138 }
 139
 140 inline
 141 int WordList::status() const {
 142   return first->status;
 143 }
 144
 145 inline
 146 bool WordList::isValid() const {
 147   return (__size > 0 && posToStatus != 0);
 148 }
 149
 150 } //namespace freeRecite end.
 151
 152 #endif