contrib/zstd/lib/common/fse.h

   1 /* ******************************************************************
   2    FSE : Finite State Entropy codec
   3    Public Prototypes declaration
   4    Copyright (C) 2013-2016, Yann Collet.
   5
   6    BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
   7
   8    Redistribution and use in source and binary forms, with or without
   9    modification, are permitted provided that the following conditions are
  10    met:
  11
  12        * Redistributions of source code must retain the above copyright
  13    notice, this list of conditions and the following disclaimer.
  14        * Redistributions in binary form must reproduce the above
  15    copyright notice, this list of conditions and the following disclaimer
  16    in the documentation and/or other materials provided with the
  17    distribution.
  18
  19    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31    You can contact the author at :
  32    - Source repository : https://github.com/Cyan4973/FiniteStateEntropy
  33 ****************************************************************** */
  34 #ifndef FSE_H
  35 #define FSE_H
  36
  37 #if defined (__cplusplus)
  38 extern "C" {
  39 #endif
  40
  41
  42 /*-*****************************************
  43 *  Dependencies
  44 ******************************************/
  45 #include <stddef.h>    /* size_t, ptrdiff_t */
  46
  47
  48 /*-*****************************************
  49 *  FSE_PUBLIC_API : control library symbols visibility
  50 ******************************************/
  51 #if defined(FSE_DLL_EXPORT) && (FSE_DLL_EXPORT==1) && defined(__GNUC__) && (__GNUC__ >= 4)
  52 #  define FSE_PUBLIC_API __attribute__ ((visibility ("default")))
  53 #elif defined(FSE_DLL_EXPORT) && (FSE_DLL_EXPORT==1)   /* Visual expected */
  54 #  define FSE_PUBLIC_API __declspec(dllexport)
  55 #elif defined(FSE_DLL_IMPORT) && (FSE_DLL_IMPORT==1)
  56 #  define FSE_PUBLIC_API __declspec(dllimport) /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/
  57 #else
  58 #  define FSE_PUBLIC_API
  59 #endif
  60
  61 /*------   Version   ------*/
  62 #define FSE_VERSION_MAJOR    0
  63 #define FSE_VERSION_MINOR    9
  64 #define FSE_VERSION_RELEASE  0
  65
  66 #define FSE_LIB_VERSION FSE_VERSION_MAJOR.FSE_VERSION_MINOR.FSE_VERSION_RELEASE
  67 #define FSE_QUOTE(str) #str
  68 #define FSE_EXPAND_AND_QUOTE(str) FSE_QUOTE(str)
  69 #define FSE_VERSION_STRING FSE_EXPAND_AND_QUOTE(FSE_LIB_VERSION)
  70
  71 #define FSE_VERSION_NUMBER  (FSE_VERSION_MAJOR *100*100 + FSE_VERSION_MINOR *100 + FSE_VERSION_RELEASE)
  72 FSE_PUBLIC_API unsigned FSE_versionNumber(void);   /**< library version number; to be used when checking dll version */
  73
  74 /*-****************************************
  75 *  FSE simple functions
  76 ******************************************/
  77 /*! FSE_compress() :
  78     Compress content of buffer 'src', of size 'srcSize', into destination buffer 'dst'.
  79     'dst' buffer must be already allocated. Compression runs faster is dstCapacity >= FSE_compressBound(srcSize).
  80     @return : size of compressed data (<= dstCapacity).
  81     Special values : if return == 0, srcData is not compressible => Nothing is stored within dst !!!
  82                      if return == 1, srcData is a single byte symbol * srcSize times. Use RLE compression instead.
  83                      if FSE_isError(return), compression failed (more details using FSE_getErrorName())
  84 */
  85 FSE_PUBLIC_API size_t FSE_compress(void* dst, size_t dstCapacity,
  86                              const void* src, size_t srcSize);
  87
  88 /*! FSE_decompress():
  89     Decompress FSE data from buffer 'cSrc', of size 'cSrcSize',
  90     into already allocated destination buffer 'dst', of size 'dstCapacity'.
  91     @return : size of regenerated data (<= maxDstSize),
  92               or an error code, which can be tested using FSE_isError() .
  93
  94     ** Important ** : FSE_decompress() does not decompress non-compressible nor RLE data !!!
  95     Why ? : making this distinction requires a header.
  96     Header management is intentionally delegated to the user layer, which can better manage special cases.
  97 */
  98 FSE_PUBLIC_API size_t FSE_decompress(void* dst,  size_t dstCapacity,
  99                                const void* cSrc, size_t cSrcSize);
 100
 101
 102 /*-*****************************************
 103 *  Tool functions
 104 ******************************************/
 105 FSE_PUBLIC_API size_t FSE_compressBound(size_t size);       /* maximum compressed size */
 106
 107 /* Error Management */
 108 FSE_PUBLIC_API unsigned    FSE_isError(size_t code);        /* tells if a return value is an error code */
 109 FSE_PUBLIC_API const char* FSE_getErrorName(size_t code);   /* provides error code string (useful for debugging) */
 110
 111
 112 /*-*****************************************
 113 *  FSE advanced functions
 114 ******************************************/
 115 /*! FSE_compress2() :
 116     Same as FSE_compress(), but allows the selection of 'maxSymbolValue' and 'tableLog'
 117     Both parameters can be defined as '0' to mean : use default value
 118     @return : size of compressed data
 119     Special values : if return == 0, srcData is not compressible => Nothing is stored within cSrc !!!
 120                      if return == 1, srcData is a single byte symbol * srcSize times. Use RLE compression.
 121                      if FSE_isError(return), it's an error code.
 122 */
 123 FSE_PUBLIC_API size_t FSE_compress2 (void* dst, size_t dstSize, const void* src, size_t srcSize, unsigned maxSymbolValue, unsigned tableLog);
 124
 125
 126 /*-*****************************************
 127 *  FSE detailed API
 128 ******************************************/
 129 /*!
 130 FSE_compress() does the following:
 131 1. count symbol occurrence from source[] into table count[]
 132 2. normalize counters so that sum(count[]) == Power_of_2 (2^tableLog)
 133 3. save normalized counters to memory buffer using writeNCount()
 134 4. build encoding table 'CTable' from normalized counters
 135 5. encode the data stream using encoding table 'CTable'
 136
 137 FSE_decompress() does the following:
 138 1. read normalized counters with readNCount()
 139 2. build decoding table 'DTable' from normalized counters
 140 3. decode the data stream using decoding table 'DTable'
 141
 142 The following API allows targeting specific sub-functions for advanced tasks.
 143 For example, it's possible to compress several blocks using the same 'CTable',
 144 or to save and provide normalized distribution using external method.
 145 */
 146
 147 /* *** COMPRESSION *** */
 148
 149 /*! FSE_count():
 150     Provides the precise count of each byte within a table 'count'.
 151     'count' is a table of unsigned int, of minimum size (*maxSymbolValuePtr+1).
 152     *maxSymbolValuePtr will be updated if detected smaller than initial value.
 153     @return : the count of the most frequent symbol (which is not identified).
 154               if return == srcSize, there is only one symbol.
 155               Can also return an error code, which can be tested with FSE_isError(). */
 156 FSE_PUBLIC_API size_t FSE_count(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize);
 157
 158 /*! FSE_optimalTableLog():
 159     dynamically downsize 'tableLog' when conditions are met.
 160     It saves CPU time, by using smaller tables, while preserving or even improving compression ratio.
 161     @return : recommended tableLog (necessarily <= 'maxTableLog') */
 162 FSE_PUBLIC_API unsigned FSE_optimalTableLog(unsigned maxTableLog, size_t srcSize, unsigned maxSymbolValue);
 163
 164 /*! FSE_normalizeCount():
 165     normalize counts so that sum(count[]) == Power_of_2 (2^tableLog)
 166     'normalizedCounter' is a table of short, of minimum size (maxSymbolValue+1).
 167     @return : tableLog,
 168               or an errorCode, which can be tested using FSE_isError() */
 169 FSE_PUBLIC_API size_t FSE_normalizeCount(short* normalizedCounter, unsigned tableLog, const unsigned* count, size_t srcSize, unsigned maxSymbolValue);
 170
 171 /*! FSE_NCountWriteBound():
 172     Provides the maximum possible size of an FSE normalized table, given 'maxSymbolValue' and 'tableLog'.
 173     Typically useful for allocation purpose. */
 174 FSE_PUBLIC_API size_t FSE_NCountWriteBound(unsigned maxSymbolValue, unsigned tableLog);
 175
 176 /*! FSE_writeNCount():
 177     Compactly save 'normalizedCounter' into 'buffer'.
 178     @return : size of the compressed table,
 179               or an errorCode, which can be tested using FSE_isError(). */
 180 FSE_PUBLIC_API size_t FSE_writeNCount (void* buffer, size_t bufferSize, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
 181
 182
 183 /*! Constructor and Destructor of FSE_CTable.
 184     Note that FSE_CTable size depends on 'tableLog' and 'maxSymbolValue' */
 185 typedef unsigned FSE_CTable;   /* don't allocate that. It's only meant to be more restrictive than void* */
 186 FSE_PUBLIC_API FSE_CTable* FSE_createCTable (unsigned tableLog, unsigned maxSymbolValue);
 187 FSE_PUBLIC_API void        FSE_freeCTable (FSE_CTable* ct);
 188
 189 /*! FSE_buildCTable():
 190     Builds `ct`, which must be already allocated, using FSE_createCTable().
 191     @return : 0, or an errorCode, which can be tested using FSE_isError() */
 192 FSE_PUBLIC_API size_t FSE_buildCTable(FSE_CTable* ct, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
 193
 194 /*! FSE_compress_usingCTable():
 195     Compress `src` using `ct` into `dst` which must be already allocated.
 196     @return : size of compressed data (<= `dstCapacity`),
 197               or 0 if compressed data could not fit into `dst`,
 198               or an errorCode, which can be tested using FSE_isError() */
 199 FSE_PUBLIC_API size_t FSE_compress_usingCTable (void* dst, size_t dstCapacity, const void* src, size_t srcSize, const FSE_CTable* ct);
 200
 201 /*!
 202 Tutorial :
 203 ----------
 204 The first step is to count all symbols. FSE_count() does this job very fast.
 205 Result will be saved into 'count', a table of unsigned int, which must be already allocated, and have 'maxSymbolValuePtr[0]+1' cells.
 206 'src' is a table of bytes of size 'srcSize'. All values within 'src' MUST be <= maxSymbolValuePtr[0]
 207 maxSymbolValuePtr[0] will be updated, with its real value (necessarily <= original value)
 208 FSE_count() will return the number of occurrence of the most frequent symbol.
 209 This can be used to know if there is a single symbol within 'src', and to quickly evaluate its compressibility.
 210 If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError()).
 211
 212 The next step is to normalize the frequencies.
 213 FSE_normalizeCount() will ensure that sum of frequencies is == 2 ^'tableLog'.
 214 It also guarantees a minimum of 1 to any Symbol with frequency >= 1.
 215 You can use 'tableLog'==0 to mean "use default tableLog value".
 216 If you are unsure of which tableLog value to use, you can ask FSE_optimalTableLog(),
 217 which will provide the optimal valid tableLog given sourceSize, maxSymbolValue, and a user-defined maximum (0 means "default").
 218
 219 The result of FSE_normalizeCount() will be saved into a table,
 220 called 'normalizedCounter', which is a table of signed short.
 221 'normalizedCounter' must be already allocated, and have at least 'maxSymbolValue+1' cells.
 222 The return value is tableLog if everything proceeded as expected.
 223 It is 0 if there is a single symbol within distribution.
 224 If there is an error (ex: invalid tableLog value), the function will return an ErrorCode (which can be tested using FSE_isError()).
 225
 226 'normalizedCounter' can be saved in a compact manner to a memory area using FSE_writeNCount().
 227 'buffer' must be already allocated.
 228 For guaranteed success, buffer size must be at least FSE_headerBound().
 229 The result of the function is the number of bytes written into 'buffer'.
 230 If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError(); ex : buffer size too small).
 231
 232 'normalizedCounter' can then be used to create the compression table 'CTable'.
 233 The space required by 'CTable' must be already allocated, using FSE_createCTable().
 234 You can then use FSE_buildCTable() to fill 'CTable'.
 235 If there is an error, both functions will return an ErrorCode (which can be tested using FSE_isError()).
 236
 237 'CTable' can then be used to compress 'src', with FSE_compress_usingCTable().
 238 Similar to FSE_count(), the convention is that 'src' is assumed to be a table of char of size 'srcSize'
 239 The function returns the size of compressed data (without header), necessarily <= `dstCapacity`.
 240 If it returns '0', compressed data could not fit into 'dst'.
 241 If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError()).
 242 */
 243
 244
 245 /* *** DECOMPRESSION *** */
 246
 247 /*! FSE_readNCount():
 248     Read compactly saved 'normalizedCounter' from 'rBuffer'.
 249     @return : size read from 'rBuffer',
 250               or an errorCode, which can be tested using FSE_isError().
 251               maxSymbolValuePtr[0] and tableLogPtr[0] will also be updated with their respective values */
 252 FSE_PUBLIC_API size_t FSE_readNCount (short* normalizedCounter, unsigned* maxSymbolValuePtr, unsigned* tableLogPtr, const void* rBuffer, size_t rBuffSize);
 253
 254 /*! Constructor and Destructor of FSE_DTable.
 255     Note that its size depends on 'tableLog' */
 256 typedef unsigned FSE_DTable;   /* don't allocate that. It's just a way to be more restrictive than void* */
 257 FSE_PUBLIC_API FSE_DTable* FSE_createDTable(unsigned tableLog);
 258 FSE_PUBLIC_API void        FSE_freeDTable(FSE_DTable* dt);
 259
 260 /*! FSE_buildDTable():
 261     Builds 'dt', which must be already allocated, using FSE_createDTable().
 262     return : 0, or an errorCode, which can be tested using FSE_isError() */
 263 FSE_PUBLIC_API size_t FSE_buildDTable (FSE_DTable* dt, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
 264
 265 /*! FSE_decompress_usingDTable():
 266     Decompress compressed source `cSrc` of size `cSrcSize` using `dt`
 267     into `dst` which must be already allocated.
 268     @return : size of regenerated data (necessarily <= `dstCapacity`),
 269               or an errorCode, which can be tested using FSE_isError() */
 270 FSE_PUBLIC_API size_t FSE_decompress_usingDTable(void* dst, size_t dstCapacity, const void* cSrc, size_t cSrcSize, const FSE_DTable* dt);
 271
 272 /*!
 273 Tutorial :
 274 ----------
 275 (Note : these functions only decompress FSE-compressed blocks.
 276  If block is uncompressed, use memcpy() instead
 277  If block is a single repeated byte, use memset() instead )
 278
 279 The first step is to obtain the normalized frequencies of symbols.
 280 This can be performed by FSE_readNCount() if it was saved using FSE_writeNCount().
 281 'normalizedCounter' must be already allocated, and have at least 'maxSymbolValuePtr[0]+1' cells of signed short.
 282 In practice, that means it's necessary to know 'maxSymbolValue' beforehand,
 283 or size the table to handle worst case situations (typically 256).
 284 FSE_readNCount() will provide 'tableLog' and 'maxSymbolValue'.
 285 The result of FSE_readNCount() is the number of bytes read from 'rBuffer'.
 286 Note that 'rBufferSize' must be at least 4 bytes, even if useful information is less than that.
 287 If there is an error, the function will return an error code, which can be tested using FSE_isError().
 288
 289 The next step is to build the decompression tables 'FSE_DTable' from 'normalizedCounter'.
 290 This is performed by the function FSE_buildDTable().
 291 The space required by 'FSE_DTable' must be already allocated using FSE_createDTable().
 292 If there is an error, the function will return an error code, which can be tested using FSE_isError().
 293
 294 `FSE_DTable` can then be used to decompress `cSrc`, with FSE_decompress_usingDTable().
 295 `cSrcSize` must be strictly correct, otherwise decompression will fail.
 296 FSE_decompress_usingDTable() result will tell how many bytes were regenerated (<=`dstCapacity`).
 297 If there is an error, the function will return an error code, which can be tested using FSE_isError(). (ex: dst buffer too small)
 298 */
 299
 300
 301 #ifdef FSE_STATIC_LINKING_ONLY
 302
 303 /* *** Dependency *** */
 304 #include "bitstream.h"
 305
 306
 307 /* *****************************************
 308 *  Static allocation
 309 *******************************************/
 310 /* FSE buffer bounds */
 311 #define FSE_NCOUNTBOUND 512
 312 #define FSE_BLOCKBOUND(size) (size + (size>>7))
 313 #define FSE_COMPRESSBOUND(size) (FSE_NCOUNTBOUND + FSE_BLOCKBOUND(size))   /* Macro version, useful for static allocation */
 314
 315 /* It is possible to statically allocate FSE CTable/DTable as a table of FSE_CTable/FSE_DTable using below macros */
 316 #define FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue)   (1 + (1<<(maxTableLog-1)) + ((maxSymbolValue+1)*2))
 317 #define FSE_DTABLE_SIZE_U32(maxTableLog)                   (1 + (1<<maxTableLog))
 318
 319 /* or use the size to malloc() space directly. Pay attention to alignment restrictions though */
 320 #define FSE_CTABLE_SIZE(maxTableLog, maxSymbolValue)   (FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue) * sizeof(FSE_CTable))
 321 #define FSE_DTABLE_SIZE(maxTableLog)                   (FSE_DTABLE_SIZE_U32(maxTableLog) * sizeof(FSE_DTable))
 322
 323
 324 /* *****************************************
 325 *  FSE advanced API
 326 *******************************************/
 327 /* FSE_count_wksp() :
 328  * Same as FSE_count(), but using an externally provided scratch buffer.
 329  * `workSpace` size must be table of >= `1024` unsigned
 330  */
 331 size_t FSE_count_wksp(unsigned* count, unsigned* maxSymbolValuePtr,
 332                  const void* source, size_t sourceSize, unsigned* workSpace);
 333
 334 /** FSE_countFast() :
 335  *  same as FSE_count(), but blindly trusts that all byte values within src are <= *maxSymbolValuePtr
 336  */
 337 size_t FSE_countFast(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize);
 338
 339 /* FSE_countFast_wksp() :
 340  * Same as FSE_countFast(), but using an externally provided scratch buffer.
 341  * `workSpace` must be a table of minimum `1024` unsigned
 342  */
 343 size_t FSE_countFast_wksp(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize, unsigned* workSpace);
 344
 345 /*! FSE_count_simple
 346  * Same as FSE_countFast(), but does not use any additional memory (not even on stack).
 347  * This function is unsafe, and will segfault if any value within `src` is `> *maxSymbolValuePtr` (presuming it's also the size of `count`).
 348 */
 349 size_t FSE_count_simple(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize);
 350
 351
 352
 353 unsigned FSE_optimalTableLog_internal(unsigned maxTableLog, size_t srcSize, unsigned maxSymbolValue, unsigned minus);
 354 /**< same as FSE_optimalTableLog(), which used `minus==2` */
 355
 356 /* FSE_compress_wksp() :
 357  * Same as FSE_compress2(), but using an externally allocated scratch buffer (`workSpace`).
 358  * FSE_WKSP_SIZE_U32() provides the minimum size required for `workSpace` as a table of FSE_CTable.
 359  */
 360 #define FSE_WKSP_SIZE_U32(maxTableLog, maxSymbolValue)   ( FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue) + ((maxTableLog > 12) ? (1 << (maxTableLog - 2)) : 1024) )
 361 size_t FSE_compress_wksp (void* dst, size_t dstSize, const void* src, size_t srcSize, unsigned maxSymbolValue, unsigned tableLog, void* workSpace, size_t wkspSize);
 362
 363 size_t FSE_buildCTable_raw (FSE_CTable* ct, unsigned nbBits);
 364 /**< build a fake FSE_CTable, designed for a flat distribution, where each symbol uses nbBits */
 365
 366 size_t FSE_buildCTable_rle (FSE_CTable* ct, unsigned char symbolValue);
 367 /**< build a fake FSE_CTable, designed to compress always the same symbolValue */
 368
 369 /* FSE_buildCTable_wksp() :
 370  * Same as FSE_buildCTable(), but using an externally allocated scratch buffer (`workSpace`).
 371  * `wkspSize` must be >= `(1<<tableLog)`.
 372  */
 373 size_t FSE_buildCTable_wksp(FSE_CTable* ct, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog, void* workSpace, size_t wkspSize);
 374
 375 size_t FSE_buildDTable_raw (FSE_DTable* dt, unsigned nbBits);
 376 /**< build a fake FSE_DTable, designed to read a flat distribution where each symbol uses nbBits */
 377
 378 size_t FSE_buildDTable_rle (FSE_DTable* dt, unsigned char symbolValue);
 379 /**< build a fake FSE_DTable, designed to always generate the same symbolValue */
 380
 381 size_t FSE_decompress_wksp(void* dst, size_t dstCapacity, const void* cSrc, size_t cSrcSize, FSE_DTable* workSpace, unsigned maxLog);
 382 /**< same as FSE_decompress(), using an externally allocated `workSpace` produced with `FSE_DTABLE_SIZE_U32(maxLog)` */
 383
 384
 385 /* *****************************************
 386 *  FSE symbol compression API
 387 *******************************************/
 388 /*!
 389    This API consists of small unitary functions, which highly benefit from being inlined.
 390    Hence their body are included in next section.
 391 */
 392 typedef struct {
 393     ptrdiff_t   value;
 394     const void* stateTable;
 395     const void* symbolTT;
 396     unsigned    stateLog;
 397 } FSE_CState_t;
 398
 399 static void FSE_initCState(FSE_CState_t* CStatePtr, const FSE_CTable* ct);
 400
 401 static void FSE_encodeSymbol(BIT_CStream_t* bitC, FSE_CState_t* CStatePtr, unsigned symbol);
 402
 403 static void FSE_flushCState(BIT_CStream_t* bitC, const FSE_CState_t* CStatePtr);
 404
 405 /**<
 406 These functions are inner components of FSE_compress_usingCTable().
 407 They allow the creation of custom streams, mixing multiple tables and bit sources.
 408
 409 A key property to keep in mind is that encoding and decoding are done **in reverse direction**.
 410 So the first symbol you will encode is the last you will decode, like a LIFO stack.
 411
 412 You will need a few variables to track your CStream. They are :
 413
 414 FSE_CTable    ct;         // Provided by FSE_buildCTable()
 415 BIT_CStream_t bitStream;  // bitStream tracking structure
 416 FSE_CState_t  state;      // State tracking structure (can have several)
 417
 418
 419 The first thing to do is to init bitStream and state.
 420     size_t errorCode = BIT_initCStream(&bitStream, dstBuffer, maxDstSize);
 421     FSE_initCState(&state, ct);
 422
 423 Note that BIT_initCStream() can produce an error code, so its result should be tested, using FSE_isError();
 424 You can then encode your input data, byte after byte.
 425 FSE_encodeSymbol() outputs a maximum of 'tableLog' bits at a time.
 426 Remember decoding will be done in reverse direction.
 427     FSE_encodeByte(&bitStream, &state, symbol);
 428
 429 At any time, you can also add any bit sequence.
 430 Note : maximum allowed nbBits is 25, for compatibility with 32-bits decoders
 431     BIT_addBits(&bitStream, bitField, nbBits);
 432
 433 The above methods don't commit data to memory, they just store it into local register, for speed.
 434 Local register size is 64-bits on 64-bits systems, 32-bits on 32-bits systems (size_t).
 435 Writing data to memory is a manual operation, performed by the flushBits function.
 436     BIT_flushBits(&bitStream);
 437
 438 Your last FSE encoding operation shall be to flush your last state value(s).
 439     FSE_flushState(&bitStream, &state);
 440
 441 Finally, you must close the bitStream.
 442 The function returns the size of CStream in bytes.
 443 If data couldn't fit into dstBuffer, it will return a 0 ( == not compressible)
 444 If there is an error, it returns an errorCode (which can be tested using FSE_isError()).
 445     size_t size = BIT_closeCStream(&bitStream);
 446 */
 447
 448
 449 /* *****************************************
 450 *  FSE symbol decompression API
 451 *******************************************/
 452 typedef struct {
 453     size_t      state;
 454     const void* table;   /* precise table may vary, depending on U16 */
 455 } FSE_DState_t;
 456
 457
 458 static void     FSE_initDState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD, const FSE_DTable* dt);
 459
 460 static unsigned char FSE_decodeSymbol(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD);
 461
 462 static unsigned FSE_endOfDState(const FSE_DState_t* DStatePtr);
 463
 464 /**<
 465 Let's now decompose FSE_decompress_usingDTable() into its unitary components.
 466 You will decode FSE-encoded symbols from the bitStream,
 467 and also any other bitFields you put in, **in reverse order**.
 468
 469 You will need a few variables to track your bitStream. They are :
 470
 471 BIT_DStream_t DStream;    // Stream context
 472 FSE_DState_t  DState;     // State context. Multiple ones are possible
 473 FSE_DTable*   DTablePtr;  // Decoding table, provided by FSE_buildDTable()
 474
 475 The first thing to do is to init the bitStream.
 476     errorCode = BIT_initDStream(&DStream, srcBuffer, srcSize);
 477
 478 You should then retrieve your initial state(s)
 479 (in reverse flushing order if you have several ones) :
 480     errorCode = FSE_initDState(&DState, &DStream, DTablePtr);
 481
 482 You can then decode your data, symbol after symbol.
 483 For information the maximum number of bits read by FSE_decodeSymbol() is 'tableLog'.
 484 Keep in mind that symbols are decoded in reverse order, like a LIFO stack (last in, first out).
 485     unsigned char symbol = FSE_decodeSymbol(&DState, &DStream);
 486
 487 You can retrieve any bitfield you eventually stored into the bitStream (in reverse order)
 488 Note : maximum allowed nbBits is 25, for 32-bits compatibility
 489     size_t bitField = BIT_readBits(&DStream, nbBits);
 490
 491 All above operations only read from local register (which size depends on size_t).
 492 Refueling the register from memory is manually performed by the reload method.
 493     endSignal = FSE_reloadDStream(&DStream);
 494
 495 BIT_reloadDStream() result tells if there is still some more data to read from DStream.
 496 BIT_DStream_unfinished : there is still some data left into the DStream.
 497 BIT_DStream_endOfBuffer : Dstream reached end of buffer. Its container may no longer be completely filled.
 498 BIT_DStream_completed : Dstream reached its exact end, corresponding in general to decompression completed.
 499 BIT_DStream_tooFar : Dstream went too far. Decompression result is corrupted.
 500
 501 When reaching end of buffer (BIT_DStream_endOfBuffer), progress slowly, notably if you decode multiple symbols per loop,
 502 to properly detect the exact end of stream.
 503 After each decoded symbol, check if DStream is fully consumed using this simple test :
 504     BIT_reloadDStream(&DStream) >= BIT_DStream_completed
 505
 506 When it's done, verify decompression is fully completed, by checking both DStream and the relevant states.
 507 Checking if DStream has reached its end is performed by :
 508     BIT_endOfDStream(&DStream);
 509 Check also the states. There might be some symbols left there, if some high probability ones (>50%) are possible.
 510     FSE_endOfDState(&DState);
 511 */
 512
 513
 514 /* *****************************************
 515 *  FSE unsafe API
 516 *******************************************/
 517 static unsigned char FSE_decodeSymbolFast(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD);
 518 /* faster, but works only if nbBits is always >= 1 (otherwise, result will be corrupted) */
 519
 520
 521 /* *****************************************
 522 *  Implementation of inlined functions
 523 *******************************************/
 524 typedef struct {
 525     int deltaFindState;
 526     U32 deltaNbBits;
 527 } FSE_symbolCompressionTransform; /* total 8 bytes */
 528
 529 MEM_STATIC void FSE_initCState(FSE_CState_t* statePtr, const FSE_CTable* ct)
 530 {
 531     const void* ptr = ct;
 532     const U16* u16ptr = (const U16*) ptr;
 533     const U32 tableLog = MEM_read16(ptr);
 534     statePtr->value = (ptrdiff_t)1<<tableLog;
 535     statePtr->stateTable = u16ptr+2;
 536     statePtr->symbolTT = ((const U32*)ct + 1 + (tableLog ? (1<<(tableLog-1)) : 1));
 537     statePtr->stateLog = tableLog;
 538 }
 539
 540
 541 /*! FSE_initCState2() :
 542 *   Same as FSE_initCState(), but the first symbol to include (which will be the last to be read)
 543 *   uses the smallest state value possible, saving the cost of this symbol */
 544 MEM_STATIC void FSE_initCState2(FSE_CState_t* statePtr, const FSE_CTable* ct, U32 symbol)
 545 {
 546     FSE_initCState(statePtr, ct);
 547     {   const FSE_symbolCompressionTransform symbolTT = ((const FSE_symbolCompressionTransform*)(statePtr->symbolTT))[symbol];
 548         const U16* stateTable = (const U16*)(statePtr->stateTable);
 549         U32 nbBitsOut  = (U32)((symbolTT.deltaNbBits + (1<<15)) >> 16);
 550         statePtr->value = (nbBitsOut << 16) - symbolTT.deltaNbBits;
 551         statePtr->value = stateTable[(statePtr->value >> nbBitsOut) + symbolTT.deltaFindState];
 552     }
 553 }
 554
 555 MEM_STATIC void FSE_encodeSymbol(BIT_CStream_t* bitC, FSE_CState_t* statePtr, U32 symbol)
 556 {
 557     FSE_symbolCompressionTransform const symbolTT = ((const FSE_symbolCompressionTransform*)(statePtr->symbolTT))[symbol];
 558     const U16* const stateTable = (const U16*)(statePtr->stateTable);
 559     U32 const nbBitsOut  = (U32)((statePtr->value + symbolTT.deltaNbBits) >> 16);
 560     BIT_addBits(bitC, statePtr->value, nbBitsOut);
 561     statePtr->value = stateTable[ (statePtr->value >> nbBitsOut) + symbolTT.deltaFindState];
 562 }
 563
 564 MEM_STATIC void FSE_flushCState(BIT_CStream_t* bitC, const FSE_CState_t* statePtr)
 565 {
 566     BIT_addBits(bitC, statePtr->value, statePtr->stateLog);
 567     BIT_flushBits(bitC);
 568 }
 569
 570
 571 /* ======    Decompression    ====== */
 572
 573 typedef struct {
 574     U16 tableLog;
 575     U16 fastMode;
 576 } FSE_DTableHeader;   /* sizeof U32 */
 577
 578 typedef struct
 579 {
 580     unsigned short newState;
 581     unsigned char  symbol;
 582     unsigned char  nbBits;
 583 } FSE_decode_t;   /* size == U32 */
 584
 585 MEM_STATIC void FSE_initDState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD, const FSE_DTable* dt)
 586 {
 587     const void* ptr = dt;
 588     const FSE_DTableHeader* const DTableH = (const FSE_DTableHeader*)ptr;
 589     DStatePtr->state = BIT_readBits(bitD, DTableH->tableLog);
 590     BIT_reloadDStream(bitD);
 591     DStatePtr->table = dt + 1;
 592 }
 593
 594 MEM_STATIC BYTE FSE_peekSymbol(const FSE_DState_t* DStatePtr)
 595 {
 596     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 597     return DInfo.symbol;
 598 }
 599
 600 MEM_STATIC void FSE_updateState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
 601 {
 602     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 603     U32 const nbBits = DInfo.nbBits;
 604     size_t const lowBits = BIT_readBits(bitD, nbBits);
 605     DStatePtr->state = DInfo.newState + lowBits;
 606 }
 607
 608 MEM_STATIC BYTE FSE_decodeSymbol(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
 609 {
 610     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 611     U32 const nbBits = DInfo.nbBits;
 612     BYTE const symbol = DInfo.symbol;
 613     size_t const lowBits = BIT_readBits(bitD, nbBits);
 614
 615     DStatePtr->state = DInfo.newState + lowBits;
 616     return symbol;
 617 }
 618
 619 /*! FSE_decodeSymbolFast() :
 620     unsafe, only works if no symbol has a probability > 50% */
 621 MEM_STATIC BYTE FSE_decodeSymbolFast(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
 622 {
 623     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 624     U32 const nbBits = DInfo.nbBits;
 625     BYTE const symbol = DInfo.symbol;
 626     size_t const lowBits = BIT_readBitsFast(bitD, nbBits);
 627
 628     DStatePtr->state = DInfo.newState + lowBits;
 629     return symbol;
 630 }
 631
 632 MEM_STATIC unsigned FSE_endOfDState(const FSE_DState_t* DStatePtr)
 633 {
 634     return DStatePtr->state == 0;
 635 }
 636
 637
 638
 639 #ifndef FSE_COMMONDEFS_ONLY
 640
 641 /* **************************************************************
 642 *  Tuning parameters
 643 ****************************************************************/
 644 /*!MEMORY_USAGE :
 645 *  Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.)
 646 *  Increasing memory usage improves compression ratio
 647 *  Reduced memory usage can improve speed, due to cache effect
 648 *  Recommended max value is 14, for 16KB, which nicely fits into Intel x86 L1 cache */
 649 #ifndef FSE_MAX_MEMORY_USAGE
 650 #  define FSE_MAX_MEMORY_USAGE 14
 651 #endif
 652 #ifndef FSE_DEFAULT_MEMORY_USAGE
 653 #  define FSE_DEFAULT_MEMORY_USAGE 13
 654 #endif
 655
 656 /*!FSE_MAX_SYMBOL_VALUE :
 657 *  Maximum symbol value authorized.
 658 *  Required for proper stack allocation */
 659 #ifndef FSE_MAX_SYMBOL_VALUE
 660 #  define FSE_MAX_SYMBOL_VALUE 255
 661 #endif
 662
 663 /* **************************************************************
 664 *  template functions type & suffix
 665 ****************************************************************/
 666 #define FSE_FUNCTION_TYPE BYTE
 667 #define FSE_FUNCTION_EXTENSION
 668 #define FSE_DECODE_TYPE FSE_decode_t
 669
 670
 671 #endif   /* !FSE_COMMONDEFS_ONLY */
 672
 673
 674 /* ***************************************************************
 675 *  Constants
 676 *****************************************************************/
 677 #define FSE_MAX_TABLELOG  (FSE_MAX_MEMORY_USAGE-2)
 678 #define FSE_MAX_TABLESIZE (1U<<FSE_MAX_TABLELOG)
 679 #define FSE_MAXTABLESIZE_MASK (FSE_MAX_TABLESIZE-1)
 680 #define FSE_DEFAULT_TABLELOG (FSE_DEFAULT_MEMORY_USAGE-2)
 681 #define FSE_MIN_TABLELOG 5
 682
 683 #define FSE_TABLELOG_ABSOLUTE_MAX 15
 684 #if FSE_MAX_TABLELOG > FSE_TABLELOG_ABSOLUTE_MAX
 685 #  error "FSE_MAX_TABLELOG > FSE_TABLELOG_ABSOLUTE_MAX is not supported"
 686 #endif
 687
 688 #define FSE_TABLESTEP(tableSize) ((tableSize>>1) + (tableSize>>3) + 3)
 689
 690
 691 #endif /* FSE_STATIC_LINKING_ONLY */
 692
 693
 694 #if defined (__cplusplus)
 695 }
 696 #endif
 697
 698 #endif  /* FSE_H */