Matrix Science header
Public Member Functions

ms_zip Class Reference
[Mascot utilities and tools module]

Utility class for compressing and decompressing data in compress format, and compressing in gzip format. More...

#include <ms_zip.hpp>

Inheritance diagram for ms_zip:
Inheritance graph
[legend]
Collaboration diagram for ms_zip:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 ms_zip (const bool isZipped, const unsigned char *buffer, const unsigned long len)
 Buffer mode constructor (only for C++).
 ms_zip (const bool isZipped, const std::string &buffer)
 Buffer mode constructor.
 ms_zip (const ms_zip &src)
 Copying constructor.
 ms_zip (const bool isZipped)
 Streaming mode constructor.
void appendErrors (const ms_errors &src)
 Copies all errors from another instance and appends them at the end of own list.
void clearAllErrors ()
 Remove all errors from the current list of errors.
std::string compressMore (const std::string &dataIn)
 Feed more data to the compressor and retrieve the next chunk of compressed data.
void compressMore (const unsigned char *dataIn, const unsigned long inputLen, unsigned char *dataOut, unsigned long *outputLen)
 Feed more data to the compressor and retrieve the next chunk of compressed data.
void copyFrom (const ms_errors *right)
 Use this member to make a copy of another instance.
void copyFrom (const ms_zip *right)
 Call this member to copy all the information from another instance.
const ms_errsgetErrorHandler () const
 Retrive the error object using this function to get access to all errors and error parameters.
int getLastError () const
 Return the error description of the last error that occurred.
std::string getLastErrorString () const
 Return the error description of the last error that occurred.
unsigned long getUnZipped (unsigned char *buffer, const unsigned long len) const
 Return the uncompressed buffer.
std::string getUnZipped () const
 Return the uncompressed buffer.
unsigned long getUnZippedLen () const
 Return the length of the uncompressed buffer.
unsigned long getZipped (unsigned char *buffer, const unsigned long len) const
 Return the compressed buffer.
std::string getZipped () const
 Return the compressed buffer.
unsigned long getZippedLen () const
 Return the length of the compressed buffer.
bool isValid () const
 Call this function to determine if there have been any errors.
ms_zipoperator= (const ms_zip &right)
 C++ style assignment operator.

Detailed Description

Utility class for compressing and decompressing data in compress format, and compressing in gzip format.


Constructor & Destructor Documentation

ms_zip ( const bool  isZipped,
const unsigned char *  buffer,
const unsigned long  len 
)

Buffer mode constructor (only for C++).

ms_zip can be used to compress and uncompress a small amount of data (less than 10 MB) in a buffer, or in streaming compression mode. When decompressing, the only supported data format is data compressed by ms_zip.

In buffer mode, the first four bytes of the compressed buffer are used to store the length of the uncompressed data as an unsigned 32 bit integer (little endian) format. No other headers are written. The object will hold a copy of both the compressed and uncompressed data, so it is not suitable for use with large amounts of data. After creating the object, call isValid() to determine if there are any errors. The errors can be retrieved using getLastErrorString().

Possible errors are:

Parameters:
isZippedshould be true if the passed buffer contains compressed data.
bufferis a pointer to the compressed or uncompressed data. If it is uncompressed, there is no assumption that the data is null terminated.
lenis the length of the passed buffer.
ms_zip ( const bool  isZipped,
const std::string &  buffer 
)

Buffer mode constructor.

ms_zip can be used to compress and uncompress a small amount of data (less than 10 MB) in a buffer, or in streaming compression mode. When decompressing, the only supported data format is data compressed by ms_zip.

In buffer mode, the first four bytes of the compressed buffer are used to store the length of the uncompressed data as an unsigned 32 bit integer (little endian) format. No other headers are written. The object will hold a copy of both the compressed and uncompressed data, so it is not suitable for use with large amounts of data. After creating the object, call isValid() to determine if there are any errors. The errors can be retrieved using getLastErrorString().

Possible errors are:

Parameters:
isZippedshould be true if the passed buffer contains compressed data.
bufferis a string that contains the compressed or uncompressed data. If it is uncompressed, there is no assumption that the data is null terminated. C++ programmers should be aware that a std::string constructor needs to be passed the length parameter when creating a std::string that contains binary data or a 'zero' in the data will be considered to be a null terminator for a string.
ms_zip ( const bool  isZipped ) [explicit]

Streaming mode constructor.

ms_zip can be used to compress and uncompress a small amount of data (less than 10 MB) in a buffer, or in streaming compression mode. When decompressing, the only supported data format is data compressed by ms_zip.

In streaming compression mode, the compressed data stream will start with a minimal gzip header, followed by the compressed data. The constructor does not take any input data as a parameter, unlike in buffer mode. Instead, input data is fed to the object using ms_zip::compressMore(), which returns compressed data. End of input data is indicated by passing the empty string to ms_zip::compressMore().

No streaming decompression mode is supported in this version.

If the underlying zlib library cannot be initialised, the following errors are possible:

Parameters:
isZippedmust always be false for compression mode.
ms_zip ( const ms_zip src )

Copying constructor.

Generally only used from C++, but will be called indirectly from other languages.

Parameters:
srcis the ms_zip to make a copy of.

Member Function Documentation

void appendErrors ( const ms_errors src ) [inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:
srcThe object to copy the errors across from. See Maintaining object references: two rules of thumb.
void clearAllErrors (  ) [inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:
isValid(), getLastError(), getLastErrorString(), getErrorHandler()
Examples:
common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.
void compressMore ( const unsigned char *  dataIn,
const unsigned long  inputLen,
unsigned char *  dataOut,
unsigned long *  outputLen 
)

Feed more data to the compressor and retrieve the next chunk of compressed data.

You may need to call ms_zip::compressMore() a few times with more input data until the compressed stream starts, which is indicated by returning a non-empty string.

Both the input and output strings are bounded: inputLen and outputLen must not exceed 10 MB, and outputLen must always exceed 0. If any of these conditions fail, a corresponding error will be set.

End of input data is indicated by calling ms_zip::compressMore() with inputLen equal to 0 (dataIn can be NULL). The compressor will flush the output and return the last compressed bytes. If there are more bytes to return than outputLen, you must call the method again (with inputLen equal to 0). When there is no more data to be flushed, outputLen will equal 0.

If this method is called in non-streaming mode, outputLen will be set to 0 and the error ms_errs::ERR_MSP_ZIP_NOTSTREAMING set.

Other possible error conditions:

Parameters:
dataInPointer to raw binary data to append to the compressed stream. The data is not assumed to be null terminated.
inputLenLength of data in dataIn.
dataOutPointer to the memory location where compressed data should be written.
outputLenMaximum length of data to output. outputLen will be set to the actual length of dataOut on successful return.
std::string compressMore ( const std::string &  dataIn )

Feed more data to the compressor and retrieve the next chunk of compressed data.

You may need to call ms_zip::compressMore() a few times with more input data until the compressed stream starts, which is indicated by returning a non-empty string.

Both the input and output strings are bounded: the input string length must not exceed 10 MB and the output string length will never exceed 10 MB.

End of input data is indicated by calling ms_zip::compressMore() with the empty string (length 0). The compressor will flush the output and return the last compressed bytes. If there are more bytes to return than the internal buffer allows, you must call the method again with the empty string. When there is no more data to be flushed, the returned string will be empty itself.

If this method is called in non-streaming mode, an empty string object will be returned and the error ms_errs::ERR_MSP_ZIP_NOTSTREAMING set.

Other possible error conditions:

Parameters:
dataInRaw binary data to append to the compressed stream. The data need not be null terminated. C++ programmers should be aware that a std::string constructor needs to be passed the length parameter when creating a std::string that contains binary data or a 'zero' in the data will be considered to be a null terminator for a string.
Returns:
A string (possibly empty) of raw compressed binary data.
void copyFrom ( const ms_errors right ) [inherited]

Use this member to make a copy of another instance.

Parameters:
rightis the source to initialise from
void copyFrom ( const ms_zip right )

Call this member to copy all the information from another instance.

Simply create an instance of the class using the default constructor and call this method.

Parameters:
rightis a pointer to another instance to copy from.
const ms_errs * getErrorHandler (  ) const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:
Constant pointer to the error handler
See also:
isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Examples:
common_error.cpp, and http_helper_getstring.cpp.
int getLastError (  ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:
isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Returns:
the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString (  ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:
Most recent error, warning, information or debug message

See Error Handling.

See also:
isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:
common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.
std::string getUnZipped (  ) const

Return the uncompressed buffer.

In buffer mode, return the uncompressed data; in streaming compression mode, return the most recent input value to ms_zip::compressMore().

Note:
In C++, the string will not be null terminated, so you should use the std::string::length function to determing the length of the data.
Note:
In Perl, the length function can also be used on the returned string. The uncompressed data may be binary or text.
Returns:
uncompressed data as a string
unsigned long getUnZipped ( unsigned char *  buffer,
const unsigned long  len 
) const

Return the uncompressed buffer.

In buffer mode, return the uncompressed data; in streaming compression mode, return the most recent input value to ms_zip::compressMore().

Parameters:
bufferis the location where the uncompressed data will be copied to. The calling application should make sure that the buffer is long enough. Use getUnZippedLen() to find the length of the uncompressed data.
lenis the length of the passed buffer.
Returns:
The number of bytes copied to the buffer.
unsigned long getUnZippedLen (  ) const

Return the length of the uncompressed buffer.

Returns:
The length, in bytes of the uncompressed data
std::string getZipped (  ) const

Return the compressed buffer.

In buffer mode, return the compressed data; in streaming compression mode, return the most recent value from ms_zip::compressMore().

Note:
In C++, the string will not be null terminated, so you should use the std::string::length function to determing the length of the data.
Note:
In Perl, the length function can be used on the returned string.
Returns:
compressed data as a string
unsigned long getZipped ( unsigned char *  buffer,
const unsigned long  len 
) const

Return the compressed buffer.

In buffer mode, return the compressed data; in streaming compression mode, return the most recent value from ms_zip::compressMore().

Parameters:
bufferis the location where the compressed data will be copied to. The calling application should make sure that the buffer is long enough. Use getZippedLen() to find the length of the compressed data.
lenis the length of the passed buffer.
Returns:
The number of bytes copied to the buffer.
unsigned long getZippedLen (  ) const

Return the length of the compressed buffer.

Returns:
The length, in bytes of the compressed data
bool isValid (  ) const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:
True is no fatal error occured
See also:
getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Examples:
common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

The documentation for this class was generated from the following files:
Copyright © 2016 Matrix Science Ltd.  All Rights Reserved. Generated on Fri Jun 2 2017 01:44:55