BmnFileProcessingFlags.h

Go to the documentation of this file.

#pragma once
#ifndef BmnFileProcessingFlags_h
#define BmnFileProcessingFlags_h
 
// Other BMN targets' header
#include "BmnEnums.h"
// std:: headers
#include <cstdint>
 
/*
 * An enum type that tells us which exactly file-reader type is used.
 * If one adds additional compression libraries into BM@N, add them to the list.
 * @note Check "ReadMe.md" for more info about the available types
 */
enum class BmnFileType : uint8_t
{
    Unknown,
    Raw,
    ZStd,
    ZLib,
    ZLib_ng,
    XZ_LZMA,
};
 
/*
 * A method that appends an enum into a string
 * @tparam T A string-type parameter that supports operator+= with strings
 * @param initialString A string onto which a file type will be appended
 * @param fileType A type of file that should be appended onto the string
 * @return initialString with a file-type string appended
 */
template<typename T>
inline T& operator+=(T& initialString, const BmnFileType fileType)
{
    // I don't think we need a type trait here - various string classes are written differently and might
    // even be represented as a standard array underneath or non-template classes without internal using declaration
    switch (fileType) {
        case BmnFileType::Raw:
            return initialString += "Raw";
        case BmnFileType::ZStd:
            return initialString += "ZStd";
        case BmnFileType::ZLib:
            return initialString += "ZLib";
        case BmnFileType::ZLib_ng:
            return initialString += "ZLib_ng";
        case BmnFileType::XZ_LZMA:
            return initialString += "XZ_LZMA";
        case BmnFileType::Unknown:
        default:
            return initialString += "Unknown";
    }
}
 
/*
 * A method that concatenates a string and an enum
 * @tparam T A string-type parameter that supports operator+= with strings
 * @param initialString An initial string that should be concatenated with an enum
 * @param fileType A type of file that should be concatenated with the string
 * @return A new concatenated string built from initialString and fileType
 */
template<typename T>
[[nodiscard]] inline T operator+(const T& initialString, const BmnFileType fileType)
{
    T aReturnString{initialString};
    aReturnString += fileType;
    return aReturnString;
}
 
enum class BmnFileStreamResults : uint8_t
{
    // Read was successful
    Success,
    // The file read has just reached EOF
    ReachedEOF,
    // Arguments (parameters) passed to a stream function are invalid
    InvalidParameters,
    // Trying to use a file that's in bad state already
    TryingToReadBadStream,
    // Trying to use a file while it's not open
    FileNotOpen,
    // Some unexpected error
    UnexpectedFail
};
 
/*
 * An enum type that tells us how to write/read files. These values always must be set
 * before an input/output file is open! Otherwise, flags will be just omitted.
 * @note Different file-processing libraries/systems may require various flags. Flags
 * that are supported will be consumed, while others will be neglected. For instance,
 * if a compression library doesn't support various compression levels, setting
 * `MaximalCompression` will behave as if `DefaultCompression` is set
 * @warning All files are managed as binaries!
 */
enum class BmnBinaryFileProcessingOptions : uint32_t
{
    // If None, all default parameters will be used
    None = 0,
    // o o o o o o OPEN-MODE FLAGS o o o o o o
 
    // For writing files
    WriteBinary = 1 << 0,
    // For reading files
    ReadBinary = 1 << 1,
    // Not to remove data before writing a file (if not used, all old data will be lost)
    LeaveOldData = 1 << 2,
    // Useful if LeaveOldData is on and writing into a file. Then, the starting position will be 0
    StartFromNull = 1 << 3,
    // Useful if LeaveOldData is on and writing into a file. Then, the starting position will be at the end of the file
    StartFromEnd = 1 << 4,
    // Forces to always write at the end of the file. Seek position will not work
    AlwaysWriteAtTheEnd = 1 << 5,
 
    // o o o o o o COMPRESSION FLAGS o o o o o o
 
    // Uses maximal compression strength for writing if the underlying library supports different compression levels.
    // Compressing might be VERY SLOW!
    MaximalCompression = 1 << 6,
    // Uses increased compression strength for writing if the underlying library supports different compression levels.
    // Compressing will most likely be slow!
    HighCompression = 1 << 7,
    // Uses increased, but not significantly, compression strength for writing if the underlying library supports
    // different compression levels.
    NormalCompression = 1 << 7,
    // Uses default compression strength for writing if the underlying library supports different compression levels.
    DefaultCompression = 1 << 9,
    // Uses some lower-level compression strength to improve compression speed, if the underlying library supports
    // different compression levels.
    LowCompression = 1 << 10,
    // The compression speed will be maximal, but the resulting compression ratio will most likely no be that high.
    // Usable if the underlying library supports different compression levels.
    MinimalCompression = 1 << 11,
    // Compression will consume a lot of memory - it will be able to look for similar patterns over the bigger portion
    // of the file. Most likely, this will increase the compression time, while the resulting compression ratio will be
    // improved. Usable if the underlying library supports this feature.
    HighCompressionMemory = 1 << 12,
    // Compression will consume more memory - it will be able to look for similar patterns over the bigger portion of
    // the file. Most likely, this will increase the compression time, while the resulting compression ratio will be
    // improved. Usable if the underlying library supports this feature.
    IntermediateCompressionMemory = 1 << 13,
    // Compression will consume default amount of memory, according to the library specifications. Usable if the
    // underlying library supports this feature.
    DefaultCompressionMemory = 1 << 14,
 
    // NOTE: additional flags might be added in the future
};
MAKE_ENUM_BITMASK(BmnBinaryFileProcessingOptions);
 
constexpr BmnBinaryFileProcessingOptions cg_writeFileFlags =
    BmnBinaryFileProcessingOptions::WriteBinary | BmnBinaryFileProcessingOptions::LeaveOldData
    | BmnBinaryFileProcessingOptions::StartFromNull | BmnBinaryFileProcessingOptions::StartFromEnd
    | BmnBinaryFileProcessingOptions::AlwaysWriteAtTheEnd;
 
constexpr BmnBinaryFileProcessingOptions cg_compressionIntensityFlags =
    BmnBinaryFileProcessingOptions::MaximalCompression | BmnBinaryFileProcessingOptions::HighCompression
    | BmnBinaryFileProcessingOptions::NormalCompression | BmnBinaryFileProcessingOptions::DefaultCompression
    | BmnBinaryFileProcessingOptions::LowCompression | BmnBinaryFileProcessingOptions::MinimalCompression;
 
constexpr BmnBinaryFileProcessingOptions cg_compressionMemoryFlags =
    BmnBinaryFileProcessingOptions::HighCompressionMemory
    | BmnBinaryFileProcessingOptions::IntermediateCompressionMemory
    | BmnBinaryFileProcessingOptions::DefaultCompressionMemory;
 
#endif   // BmnFileProcessingFlags_h