MSNumpress.h

Go to the documentation of this file.

/*
        MSNumpress.hpp
        johan.teleman@immun.lth.se
        
        This distribution goes under the BSD 3-clause license. If you prefer to use Apache
        version 2.0, that is also available at https://github.com/fickludd/ms-numpress
        Copyright (c) 2013, Johan Teleman
        All rights reserved.

        Redistribution and use in source and binary forms, with or without modification,
        are permitted provided that the following conditions are met:

*         Redistributions of source code must retain the above copyright notice, this list
        of conditions and the following disclaimer.
*        Redistributions in binary form must reproduce the above copyright notice, this
        list of conditions and the following disclaimer in the documentation and/or other
        materials provided with the distribution.
*        Neither the name of the Lund University nor the names of its contributors may be
        used to endorse or promote products derived from this software without specific
        prior written permission.

        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
        OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
        SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
        OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/*
  ==================== encodeInt ====================
  Some of the encodings described below use a integer compression referred to simply as 
  
  encodeInt()
 
  The algorithm is similar to other variable length integer encodings,
  such as the SQLite Variable-Length Integers encoding, but it uses half
  bytes in its encoding procedure.

  This encoding works on a 4 byte integer, by truncating initial zeros or ones.
  If the initial (most significant) half byte is 0x0 or 0xf, the number of such 
  halfbytes starting from the most significant is stored in a halfbyte. This initial 
  count is then followed by the rest of the ints halfbytes, in little-endian order. 
  A count halfbyte c of

    0 <= c <= 8     is interpreted as an initial c    0x0 halfbytes 
    9 <= c <= 15    is interpreted as an initial (c-8)  0xf halfbytes

  Example:

  int   c   rest
  0   =>  0x8
  -1  =>  0xf   0xf
   2  =>  0x7   0x2
  23  =>  0x6   0x7 0x1
  2047  =>  0x5   0xf 0xf 0xf

  Note that the algorithm returns a char array in which the half bytes are
  stored in the lower 4 bits of each element. Since the first element is a
  count half byte, the maximal length of the encoded data is 9 half bytes
  (1 count half byte + 8 half bytes for a 4-byte integer).

 */

#ifndef OPENMS_MATH_MISC_MSNUMPRESS_H
#define OPENMS_MATH_MISC_MSNUMPRESS_H

#include <cstddef>
#include <vector>

// defines whether to throw an exception when a number cannot be encoded safely
// with the given parameters
#ifndef MS_NUMPRESS_THROW_ON_OVERFLOW
#define MS_NUMPRESS_THROW_ON_OVERFLOW true
#endif

namespace ms {
namespace numpress {

namespace MSNumpress {
  
  double optimalLinearFixedPoint(
    const double *data,
    size_t dataSize);
  
    double optimalLinearFixedPointMass(
            const double *data,
            size_t dataSize,
            double mass_acc);

  size_t encodeLinear(
    const double *data, 
    const size_t dataSize, 
    unsigned char *result,
    double fixedPoint);
  
  void encodeLinear(
    const std::vector<double> &data, 
    std::vector<unsigned char> &result,
    double fixedPoint);

  size_t decodeLinear(
    const unsigned char *data,
    const size_t dataSize,
    double *result);
  
  void decodeLinear(
    const std::vector<unsigned char> &data,
    std::vector<double> &result);
    
  
  
  size_t encodeSafe(
    const double *data, 
    const size_t dataSize, 
    unsigned char *result);
  
  
  size_t decodeSafe(
    const unsigned char *data,
    const size_t dataSize,
    double *result);
  

  size_t encodePic(
    const double *data, 
    const size_t dataSize, 
    unsigned char *result);
    
  void encodePic(
    const std::vector<double> &data,
    std::vector<unsigned char> &result);

  size_t decodePic(
    const unsigned char *data,
    const size_t dataSize,
    double *result);
  
  void decodePic(
    const std::vector<unsigned char> &data,
    std::vector<double> &result);



  double optimalSlofFixedPoint(
    const double *data, 
    size_t dataSize);

  size_t encodeSlof(
    const double *data, 
    const size_t dataSize, 
    unsigned char *result,
    double fixedPoint);
    
  void encodeSlof(
    const std::vector<double> &data,
    std::vector<unsigned char> &result,
    double fixedPoint);

  size_t decodeSlof(
    const unsigned char *data, 
    const size_t dataSize, 
    double *result);
  
  void decodeSlof(
    const std::vector<unsigned char> &data,
    std::vector<double> &result);

} // namespace MSNumpress
} // namespace msdata
} // namespace pwiz

#endif // _MSNUMPRESS_HPP_