BmnFileReaderZLib.h

Go to the documentation of this file.

#pragma once
#ifndef BmnFileReaderZLib_h
#define BmnFileReaderZLib_h
// headers from this target
#include "BmnIArchiveLibRead.h"
#include "BmnIFileReader.h"
#include "BmnReaderCacheManager.h"
 
struct z_stream_s;
 
/*
 * A class responsible for reading files compressed with ZLib (Deflate algorithm) or GZip (internally,
 * it uses ZLib). For long, ZLib was an industry standard as it allowed for good compression ratios while
 * still working fast. Still, nowadays, there are libraries that work faster and give better compression (ZStd).
 * ZLib-ng (stands for "new generation") also implements the Deflate algorithm while achieving significantly
 * faster compression/decompression (see `BmnFileReaderZLibNG`).
 * It's advisable to allocate this class on the heap as internally it uses big std::array
 * @warning Using this class directly can result in throws if the ZLib library is not found during compilation.
 *          Therefore, it's always advisable to obtain appropriate read objects through
 *          `BmnCompressionCreateNewSuitableReaderForAFile`
 */
class BmnFileReaderZLib
    : public BmnIFileReader
    , public BmnIArchiveLibRead
{
  public:
    /*
     * A standard constructor that sets a path to the input binary (GZip or ZLib-compressed) file
     * @note The constructor will not check whether the file actually exists
     * @param fileName A path (most likely relative) to the input binary (GZip or ZLib-compressed) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZLib(const std::string& fileName = "");
 
    /*
     * A standard constructor that sets a path to the input binary (GZip or ZLib-compressed) file
     * @note The constructor will not check whether the file actually exists
     * @param fileName A path (most likely relative) to the input binary (GZip or ZLib-compressed) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZLib(std::string&& fileName);
 
    /*
     * A standard constructor that sets a path to the input binary (GZip or ZLib-compressed) file
     * @note The constructor will not check whether the file actually exists
     * @param filePath A path to the input binary (GZip or ZLib-compressed) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZLib(const std::filesystem::path& filePath);
 
    /*
     * A standard constructor that sets a path to the input binary (GZip or ZLib-compressed) file
     * @note The constructor will not check whether the file actually exists
     * @param filePath A path to the input binary (GZip or ZLib-compressed) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZLib(std::filesystem::path&& filePath);
 
    // Closes the stream while destroying the instance
    virtual ~BmnFileReaderZLib() override;
    BmnFileReaderZLib(const BmnFileReaderZLib&) = delete;
    BmnFileReaderZLib& operator=(const BmnFileReaderZLib&) = delete;
    BmnFileReaderZLib(BmnFileReaderZLib&&) noexcept = delete;
    BmnFileReaderZLib& operator=(BmnFileReaderZLib&&) noexcept = delete;
 
    // ========== BmnIFileReaderInterface ==========
 
    /*
     * Opens a file for reading. The path of the file should be provided before calling this method
     * @param processingFlags A flag that tells us how to open the file for reading. This class only supports
     * `ReadBinary` flag
     */
    virtual void Open(
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary) override;
 
    /*
     * Closes the stream and resets all internal data. After calling `Close`, it's safe to reopen using the same
     * instance of this class
     */
    virtual void Close() noexcept override;
 
    /*
     * Reads and decompresses the data while still managing caching for efficiency.
     * @param dataToFill A buffer that will be filled with uncompressed data
     * @param sizeToFill A number of bytes that will be filled in `dataToFill`
     * @return A number of bytes that were filled in `dataToFill`. This value should almost always be the same as
     *         `sizeToFill` except when the end of the stream is reached (only if the user asked for more data than
     * possible)
     */
    virtual int64_t Read(void* dataToFill, const int64_t sizeToFill) override;
 
    /*
     * A method that tells us what's the next byte to read
     * @return A position of the next byte that should be read
     */
    [[nodiscard]] virtual int64_t Tell() const noexcept override;
 
    /*
     * A method that allows us to go to another place in the file (uncompressed data) and read from that place.
     * This method is NOT EFFICIENT as it still needs to uncompress data to reach the needed place!
     * @param value A position in uncompressed data to which one wants to move before the next read
     */
    virtual void Seek(int64_t value) override;
 
    /*
     * Check whether the reading stream is good
     * @return 'true' if no decompression error has occurred and the input-file stream is good, or 'false' otherwise
     */
    [[nodiscard]] virtual bool IsGood() const noexcept override;
 
    /*
     * Check if we have reached the file. This will tell us if we have reached EOF in the uncompressed data, not
     * in the file itself. That is, the file might be at EOF, while this method returns will return true as cache
     * still has some data
     * @return 'true' if both file and internal cache are completely read, 'false' otherwise
     */
    [[nodiscard]] virtual bool IsEOF() const noexcept override;
 
    /*
     * A method that clears bad flags after an error has occurred. Just calling this error will most likely
     * not solve the problem, and you will get an error again in the next read. That is, before calling `Read`,
     * remove the previous error source
     */
    virtual void ClearStateFlags() override;
 
    /*
     * @return 'true' if the input stream is open, or 'false' if not
     */
    [[nodiscard]] virtual bool IsOpen() const noexcept override;
 
    // ========== BmnIArchiveLib Interface ==========
 
    /*
     * A method that is called to uncompress Deflate data with ZLib
     * @param source A pointer to a buffer with the subsequent compressed data that should be uncompressed
     * @param sourceTotalSize A number of bytes available in the source buffer. If one has reached the EOF, it's ok to
     * pass a 0 here
     * @param numberOfReadBytes A number of bytes that were consumed by ZLib while decompressing. This value will be
     * set.
     * @param output A pointer to a buffer that will be filled with uncompressed data
     * @param outputTotalSize A number of bytes that may be filled in the output buffer
     * @param numberOfSetOutputBytes A number of bytes that were set while decompressing. This value will be set.
     * @return There are a few options:
     *      1. `BmnFileStreamResults::FileNotOpen` if the stream is not open
     *      2. `BmnFileStreamResults::TryingToReadBadStream` if the stream previously hit an error while it wasn't
     * cleared later
     *      3. `BmnFileStreamResults::UnexpectedFail` ZLib failed while decompressing
     *      4. `BmnFileStreamResults::ReachedEOF` ZLib reached the end of frame (in our case file)
     *      5. `BmnFileStreamResults::Success` ZLib successfully uncompressed the package
     */
    virtual BmnFileStreamResults Uncompress(const void* source,
                                            const size_t sourceTotalSize,
                                            size_t& numberOfReadBytes,
                                            void* output,
                                            const size_t outputTotalSize,
                                            size_t& numberOfSetOutputBytes) override;
 
    /*
     * If an error occurred while decompressing, this method can be called to obtain a description of the error
     * @return A description of an error that occurred while decompressing, or an empty string if no such error happened
     */
    [[nodiscard]] virtual std::string GetLastUncompressErrorDescription() const noexcept override;
 
    /*
     * @return 'false' - this class doesn't allow jumping
     */
    [[nodiscard]] virtual bool JumpsAllowed() const noexcept override;
 
    /*
     * This method will do nothing but print an error. This class doesn't allow us to efficiently jump over the
     * compressed file
     */
    virtual void JumpTo(size_t) override;
 
    /*
     * A method that tells us how many uncompressed bytes were read from an input file
     * @return A number of uncompressed bytes that passed through the ZLib
     */
    [[nodiscard]] virtual size_t GetNumberOfDecompressedBytes() const noexcept override;
 
    /*
     * A method that can be used to check if the reading stream has ended
     * @return 'true' if we have reached EOF, 'false' otherwise
     */
    [[nodiscard]] virtual bool HasReachedTheEndOfStream() const noexcept override;
 
    /*
     * A method that checks whether the last read was good or not. If not, the stream is not good anymore
     * @return 'true' if the stream is in a good state, 'false' otherwise
     */
    [[nodiscard]] virtual bool IsStreamInGoodState() const noexcept override;
 
    // ========== BmnFileReaderZLib inlines ==========
 
    [[nodiscard]] inline z_stream_s* GetUnderlyingLibraryStream() const noexcept;
    // Get number of read bytes via `GetNumberOfDecompressedBytes`
    // No need to expose `fArchiveReadManager`
 
  private:
    z_stream_s* fZlibStream;
    BmnReaderCacheManager<32ull * 1024ull, 64ull * 1024ull> fArchiveReadManager;
    size_t fNumberOfReadBytes;
    int32_t fLastReturnStatus;
    // 4 padding bytes
};
 
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
// ================== BmnFileReaderZLib inline methods ==================
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
 
[[nodiscard]] inline z_stream_s* BmnFileReaderZLib::GetUnderlyingLibraryStream() const noexcept
{
    return fZlibStream;
}
 
#endif   // BmnFileReaderZLib_h