The Fib multimedia system
Fib is a system for storing multimedia data (like images or films).
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
cDomainIntegerBasis.h
Go to the documentation of this file.
1 /**
2  * @class cDomainIntegerBasis
3  * file name: cDomainIntegerBasis.h
4  * @author Betti Oesterholz
5  * @date 13.05.2009
6  * @mail webmaster@BioKom.info
7  *
8  * System: C++
9  *
10  * This class represents a domain for integer numbers.
11  * Copyright (C) @c LGPL3 2009 Betti Oesterholz
12  *
13  * This program is free software: you can redistribute it and/or modify
14  * it under the terms of the GNU Lesser General Public License (LGPL) as
15  * published by the Free Software Foundation, either version 3 of the
16  * License, or any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU Lesser General Public License for more details.
22  *
23  * You should have received a copy of the GNU Lesser General Public License
24  * along with this program. If not, see <http://www.gnu.org/licenses/>.
25  *
26  *
27  * This file contains the basisclass of all integer Fib -domains.
28  * It's not possible to create instances from this class.
29  *
30  */
31 /*
32 History:
33 13.05.2009 Oesterholz created
34 12.05.2010 Oesterholz scalingfactor moved from cDomainSingle to cDomainIntegerBasis
35 16.05.2010 Oesterholz getCompressedSizeForScalingFactor() added
36 */
37 
38 #ifndef ___C_DOMAIN_INTEGER_BASIS_H__
39 #define ___C_DOMAIN_INTEGER_BASIS_H__
40 
41 #include "version.h"
42 #include "fibDatatyps.h"
43 
44 #include "cDomainSingle.h"
45 
46 #include <list>
47 
48 
49 namespace fib{
50 
51 
53 protected:
54  /**
55  * The scaling factor for the integer domains.
56  */
58 
59  /**
60  * The constructor for scalar/ number domains.
61  *
62  * @param dInScalingFactor the scaling factor for the domain
63  * the scaling factor has to be greater 0.0
64  */
65  cDomainIntegerBasis( const doubleFib dInScalingFactor );
66 
67 
68 public:
69 
70  /**
71  * This method returns the scalingfactor of the domain.
72  *
73  * @return the scalingfactor of the domain
74  */
76 
77  /**
78  * This method returns the scaled value of the given value lValue.
79  *
80  * @param lValue the value to scale
81  * @return the scaled value of the given value lValue
82  */
83  doubleFib scale( const longFib lValue ) const;
84 
85 
86  /**
87  * This Method checks if the given domain is equal to this domain.
88  *
89  * @param domain the domain which should be equal to this domain
90  * @return true if the given domain is equal to this domain, else false
91  */
92  virtual bool operator==( const cDomain &domain ) const;
93 
94  /**
95  * This method checks if the given value is an element of the
96  * unscaled domain. If the value dValue is an element of the
97  * unscaled domain true is returned, else false.
98  *
99  * @param dValue the value for which to check, if it is an element of
100  * the unscaled domain
101  * @return if the value dValue is an element of the unscaled
102  * domain true true is returned, else false
103  */
104  virtual bool isUnscaledElement( const longFib dValue ) const = 0;
105 
106 
107  /**
108  * This method round the given value dValue to an value in the
109  * unscaled domain of this object.
110  * The rounded vale will be the unscaled value with the minimal
111  * distance to the given value lValue. If more of these exists the
112  * smales will be returned.
113  *
114  * @param lValue the value which should be rounded
115  * @return the rounded unscaled value of lValue
116  */
117  virtual longFib roundUnscaled( const longFib lValue ) const = 0;
118 
119 
120  /**
121  * This method returns the biggest value in the unscaled domain.
122  *
123  * @return the biggest value in the unscaled domain
124  */
125  virtual longFib getMaximumUnscaled( ) const = 0;
126 
127 
128  /**
129  * This method returns the smalest value in the unscaled domain.
130  *
131  * @return the smalest value in the unscaled domain
132  */
133  virtual longFib getMinimumUnscaled( ) const = 0;
134 
135 
136  /**
137  * This method returns the nullvalue of the unscaled domain.
138  * The nullvalue is the value 0 rounded to an value in the unscaled
139  * domain.
140  *
141  * @return the nullvalue of the domain
142  */
143  virtual longFib getNullUnscaled( ) const = 0;
144 
145 
146  /**
147  * This Method clones this object.
148  *
149  * @return a clone of this object
150  */
151  virtual cDomainIntegerBasis *clone() const = 0;
152 
153  /**
154  * This method stores the given unscaled value lValue in the compressed
155  * fib -format for the domain into the given stream.
156  * It is needed because the stream can yust store byts but the size of
157  * fib -elements can be any number of bits. Because of that ther have to
158  * be a possibility to exchange the missing bits betwean the fib -elements.
159  *
160  * @see cFibElement::store
161  * @param lValue the value to store
162  * @param stream the stream where this domain should be stored to
163  * @param cRestBits the not yet writen bits which should be stored
164  * @param uiRestBitPosition the number of bits in the cRestBits which
165  * should be writen respectively containing valid information
166  * @return true if the domain is stored, else false
167  */
168  virtual bool storeUnscaledValue( longFib lValue, ostream & stream,
169  char & cRestBits, unsigned char & uiRestBitPosition ) const = 0;
170 
171 
172  /**
173  * This method restores the a value of the domain from the stream
174  * iBitStream wher it is stored in the compressed fib -format.
175  *
176  * @see storeValue
177  * @see cFibElement::restore
178  * @param iBitStream the stream where this value is stored to in,
179  * because this stream is an cReadBits, any number of bits can be
180  * readed from it
181  * @param outStatus An reference to an integervalue where the errorvalue
182  * can be stored to. If the pointer is NULL no errorvalue will be
183  * given back.
184  * possible errorvalues are:
185  * - 0 loading successful
186  * - -1 loading error, invalid stream
187  * - -2 loading error, invalid data in stream
188  * - 1 loading warning, invalid data in stream, error could be corrected
189  * - 2 loading warning, invalid data in stream, maybe the loaded
190  * object is wrong
191  */
192  virtual doubleFib restoreValue( cReadBits & iBitStream, intFib & outStatus ) const;
193 
194  /**
195  * This method restores the a unscaled integer value of the domain from
196  * the stream iBitStream, wher it is stored in the compressed fib -format.
197  *
198  * @see storeValue
199  * @see restoreValue
200  * @see storeUnscaledValue
201  * @see cFibElement::restore
202  * @param iBitStream the stream where this value is stored to in,
203  * because this stream is an cReadBits, any number of bits can be
204  * readed from it
205  * @param outStatus An reference to an integervalue where the errorvalue
206  * can be stored to. If the pointer is NULL no errorvalue will be
207  * given back.
208  * possible errorvalues are:
209  * - 0 loading successful
210  * - -1 loading error, invalid stream
211  * - -2 loading error, invalid data in stream
212  * - 1 loading warning, invalid data in stream, error could be corrected
213  * - 2 loading warning, invalid data in stream, maybe the loaded
214  * object is wrong
215  */
216  virtual longFib restoreIntegerValue( cReadBits & iBitStream, intFib & outStatus ) const = 0;
217 
218  /**
219  * This function creates creates a good domain wich contains all the
220  * numbers of the given list liValues.
221  * A domain is better than an other domain, if it takes less storage bits
222  * to store the numbers and the domain.
223  * Beware: You have to care that the returned domain is deleted. (if
224  * one was returned)
225  *
226  * @param liValues the list with the values, for which a domain is to create
227  * @return a new domain which contains all the given values liValues
228  */
229  static cDomainIntegerBasis * createGoodDomain( const list< longFib > & liValues );
230 
231 protected:
232 
233  /**
234  * This method evaluades the size for the scaling factor in bits in the
235  * compressed file form.
236  *
237  * @see storeScalingFactor()
238  * @return the size of the domain in bits in the compressed form
239  */
240  unsigned int getCompressedSizeForScalingFactor() const;
241 
242  /**
243  * This method stores the scalingfactor of this domain in the
244  * compressed fib -format into the given stream.
245  * It is needed because the stream can yust store byts but the size of
246  * fib -elements can be any number of bits. Because of that ther have to
247  * be a possibility to exchange the missing bits betwean the fib -elements.
248  *
249  * @see cFibElement::store
250  * @param stream the stream where this domain should be stored to
251  * @param cRestBits the not yet writen bits which should be stored
252  * @param uiRestBitPosition the number of bits in the cRestBits which
253  * should be writen respectively containing valid information
254  * @return true if the scalingfactor of the domain is stored, else false
255  */
256  bool storeScalingFactor( ostream & stream, char & cRestBits,
257  unsigned char & uiRestBitPosition ) const;
258 
259  /**
260  * This method restores the scalingfactore from a bitstream, wher it is
261  * stored in the compressed fib -format.
262  *
263  * @see storeScalingFactor
264  * @see restore
265  * @param iBitStream the stream where the scalingfactore is stored in,
266  * because the stream is an cReadBits, any number of bits can be
267  * readed from it
268  * @return an integervalue with the errorvalue
269  * possible errorvalues are:
270  * - 0 loading successful
271  * - -1 loading error, invalid pXmlElement
272  * - -2 loading error, invalid data in pXmlElement
273  * - 1 loading warning, invalid data in pXmlElement, error could be corrected
274  * - 2 loading warning, invalid data in pXmlElement, maybe the loaded
275  * object is wrong
276  */
277  intFib restoreScalingFactor( cReadBits & iBitStream );
278 
279  /**
280  * This function sets the scalingfactor.
281  * The scalingfactor is given as the scalingfactor in xml -format.
282  *
283  * @param szXmlScalingFactor the scalingfactor readed from an fib -xml -format
284  */
285  doubleFib setXmlScaling( const char * szXmlScalingFactor );
286 
287 
288 };//end class cDomainIntegerBasis
289 
290 
291 }//end namespace fib
292 
293 #endif