zstd/compress/hist.h

0001 /* ******************************************************************
0002  * hist : Histogram functions
0003  * part of Finite State Entropy project
0004  * Copyright (c) Yann Collet, Facebook, Inc.
0005  *
0006  *  You can contact the author at :
0007  *  - FSE source repository : https://github.com/Cyan4973/FiniteStateEntropy
0008  *  - Public forum : https://groups.google.com/forum/#!forum/lz4c
0009  *
0010  * This source code is licensed under both the BSD-style license (found in the
0011  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
0012  * in the COPYING file in the root directory of this source tree).
0013  * You may select, at your option, one of the above-listed licenses.
0014 ****************************************************************** */
0015
0016 /* --- dependencies --- */
0017 #include "../common/zstd_deps.h"   /* size_t */
0018
0019
0020 /* --- simple histogram functions --- */
0021
0022 /*! HIST_count():
0023  *  Provides the precise count of each byte within a table 'count'.
0024  * 'count' is a table of unsigned int, of minimum size (*maxSymbolValuePtr+1).
0025  *  Updates *maxSymbolValuePtr with actual largest symbol value detected.
0026  * @return : count of the most frequent symbol (which isn't identified).
0027  *           or an error code, which can be tested using HIST_isError().
0028  *           note : if return == srcSize, there is only one symbol.
0029  */
0030 size_t HIST_count(unsigned* count, unsigned* maxSymbolValuePtr,
0031                   const void* src, size_t srcSize);
0032
0033 unsigned HIST_isError(size_t code);  /*< tells if a return value is an error code */
0034
0035
0036 /* --- advanced histogram functions --- */
0037
0038 #define HIST_WKSP_SIZE_U32 1024
0039 #define HIST_WKSP_SIZE    (HIST_WKSP_SIZE_U32 * sizeof(unsigned))
0040 /* HIST_count_wksp() :
0041  *  Same as HIST_count(), but using an externally provided scratch buffer.
0042  *  Benefit is this function will use very little stack space.
0043  * `workSpace` is a writable buffer which must be 4-bytes aligned,
0044  * `workSpaceSize` must be >= HIST_WKSP_SIZE
0045  */
0046 size_t HIST_count_wksp(unsigned* count, unsigned* maxSymbolValuePtr,
0047                        const void* src, size_t srcSize,
0048                        void* workSpace, size_t workSpaceSize);
0049
0050 /* HIST_countFast() :
0051  *  same as HIST_count(), but blindly trusts that all byte values within src are <= *maxSymbolValuePtr.
0052  *  This function is unsafe, and will segfault if any value within `src` is `> *maxSymbolValuePtr`
0053  */
0054 size_t HIST_countFast(unsigned* count, unsigned* maxSymbolValuePtr,
0055                       const void* src, size_t srcSize);
0056
0057 /* HIST_countFast_wksp() :
0058  *  Same as HIST_countFast(), but using an externally provided scratch buffer.
0059  * `workSpace` is a writable buffer which must be 4-bytes aligned,
0060  * `workSpaceSize` must be >= HIST_WKSP_SIZE
0061  */
0062 size_t HIST_countFast_wksp(unsigned* count, unsigned* maxSymbolValuePtr,
0063                            const void* src, size_t srcSize,
0064                            void* workSpace, size_t workSpaceSize);
0065
0066 /*! HIST_count_simple() :
0067  *  Same as HIST_countFast(), this function is unsafe,
0068  *  and will segfault if any value within `src` is `> *maxSymbolValuePtr`.
0069  *  It is also a bit slower for large inputs.
0070  *  However, it does not need any additional memory (not even on stack).
0071  * @return : count of the most frequent symbol.
0072  *  Note this function doesn't produce any error (i.e. it must succeed).
0073  */
0074 unsigned HIST_count_simple(unsigned* count, unsigned* maxSymbolValuePtr,
0075                            const void* src, size_t srcSize);