UT_ZString.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_ZString.h (UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_ZString__
#define __UT_ZString__

#include "UT_StringHolder.h"
#include <SYS/SYS_Hash.h>

// Signals UT_ZString that its ingesting an already compressed string
namespace UT
{
    class source_is_compressed {};
}

/// Storage to hold compressed data.
///
/// This class will take a buffer of data and compress it.  You can access the
/// raw compressed data using @c compressedString(), or easily get a copy of
/// the uncompressed data by calling @c uncompress().
///
/// Since @c UT_StringRef can hold binary data, this is a convenient way of
/// compressing data that has infrequent access (or possibly never accessed).
/// For example: @code
///    void *binary_data;
///    UT_ZString  z(UT_StringRef((const char *)binary_data, binary_size));
/// @endcode
///
/// @note BLOSC compression typically works best on larger buffers with numeric
/// data.  It's faster than GZIP compression, but has worse compression.
class UT_API UT_ZString
{
public:
    enum Style
    {
        NONE,
        GZIP,
        BLOSC
    };

    /// Map the enum to a string
    static const char   *style(Style s);
    /// Map the string to an enum value
    static Style         style(const char *s);

    UT_ZString() = default;

    /// Take an uncompressed string and store the compressed result.
    UT_ZString(const UT_StringRef &src, Style style=GZIP, int level=9)
    {
        compress(src, style, level);
    }
    /// Set the compressed data given the original style.
    /// If the <tt>original_size == src.length()</tt> then we assume the string
    /// is uncompressed (unless the @c force_compressed flag is true).
    ///
    /// This matches the semantics of @c compress() (which stores the
    /// uncompressed string if the compression results in a larger buffer).
    UT_ZString(const UT_StringRef &src, Style style,
                const UT::source_is_compressed&,
                exint original_size,
                bool force_compressed=false)
    {
        setCompressedData(src, style, original_size, force_compressed);
    }

    /// Clear storage and reset values
    void        clear()
    {
        myString.clear();
        mySize = 0;
        myStyle = GZIP;
    }

    /// Store a string as compressed data, returning the compressed style.  If
    /// no compression is done, the returned style will be NONE.
    ///
    /// For GZIP compression, level can be between 1 and 9.  1 is faster, 9 is
    /// better compression (but can be significantly slower).
    Style               compress(const UT_StringRef &s,
                                Style style=GZIP,
                                int level=1);

    /// Return the uncompressed contents
    UT_StringHolder     uncompress() const;

    /// Set the class to hold an already compressed string.
    void setCompressedData(const UT_StringHolder &z, Style s,
                            exint original_size,
                            bool force_compressed=false);

    /// @{
    /// Member data access
    const UT_StringHolder       &compressedString() const { return myString; }
    Style                        compressedStyle() const { return myStyle; }
    exint                        originalSize() const { return mySize; }
    /// @}

    /// The z-string has a string if the original size is non-zero
    SYS_FORCE_INLINE
    bool isstring() const { return mySize > 0; }

    /// Test whether the string is defined or not
    SYS_FORCE_INLINE
    SYS_SAFE_BOOL       operator bool() const   { return isstring(); }

    /// @{
    /// Standard "string" type operations.
    int64               getMemoryUsage(bool inclusive) const
    {
        int64   mem = inclusive ? sizeof(*this) : 0;
        return mem += myString.getMemoryUsage(false);
    }
    SYS_HashType        hash() const
    {
        SYS_HashType    h = myString.hash();
        SYShashCombine(h, mySize);
        SYShashCombine(h, myStyle);
        return h;
    }
    friend std::size_t  hash_value(const UT_ZString &s) { return s.hash(); }
    bool        operator==(const UT_ZString &s) const
                {
                    return mySize == s.mySize
                        && myStyle == s.myStyle
                        && myString == s.myString;
                }
    /// @}

private:
    UT_StringHolder     myString;
    exint               mySize = 0;
    Style               myStyle = NONE;
};

#endif