BmnCompressionGlobalFunctions.h

Go to the documentation of this file.

#pragma once
#ifndef BmnCompressionGlobalFunctions_h
#define BmnCompressionGlobalFunctions_h
 
// headers from this target
#include "BmnFileProcessingFlags.h"
#include "BmnIFileReader.h"
// std: headers
#include <filesystem>
#include <string_view>
 
/*
 * The extensions of the archive formats which the file readers of this target are able to open
 * The extensions are written in the lower case, because they are compared case-insensitively
 */
inline constexpr std::string_view BmnCompressionArchiveExtensions[]{".zst", ".zstd", ".gz", ".gzip", ".xz", ".lzma"};
 
/*
 * A method to check whether a specific archive library was loaded (found) while building binaries.
 * If the library was found, it's safe to use it, otherwise, some unexpected throws might appear.
 * @param aLibraryType A library type one wants to check and use
 * @return 'true' if the archive library is supported, or 'false' if not
 */
[[nodiscard]] bool BmnCompressionIsArchiveLibAvailable(const BmnFileType aLibraryType) noexcept;
 
/*
 * A function that selects and creates an appropriate reader-class instance based on magic bytes of
 * the provided file. If no familiar magic bytes are found, the fill will be opened for raw-binary reading
 * @param aFilePath A path to an existing, actual and accessible file that should be read
 * @param aPreferredTypeForThisAlgorithm With this, one can choose which processing library to use if there
 *        are multiple libraries using the same algorithm. For instance, ZLib and ZLib-ng use the same Deflate algorithm
 * @return A selected appropriate file reader. The returned instance should be freed (deleted) by the caller!
 */
[[nodiscard]] BmnIFileReader* BmnCompressionCreateNewSuitableReaderForAFile(
    const std::filesystem::path& aFilePath,
    const BmnFileType aPreferredTypeForThisAlgorithm = BmnFileType::Unknown);
 
/*
 * A function that selects and creates an appropriate reader-class instance based on magic bytes of
 * the provided file. If no familiar magic bytes are found, the fill will be opened for raw-binary reading
 * @param aFilePath A path to an existing, actual and accessible file that should be read
 * @param aPreferredTypeForThisAlgorithm With this, one can choose which processing library to use if there
 *        are multiple libraries using the same algorithm. For instance, ZLib and ZLib-ng use the same Deflate algorithm
 * @return A selected appropriate file reader. The returned instance should be freed (deleted) by the caller!
 */
[[nodiscard]] BmnIFileReader* BmnCompressionCreateNewSuitableReaderForAFile(
    std::filesystem::path&& aFilePath,
    const BmnFileType aPreferredTypeForThisAlgorithm = BmnFileType::Unknown);
 
/*
 * A function that drops the trailing archive extension of a path, if there is one
 * Only the extension is analysed here, the file itself is neither opened nor required to exist
 * @param aFilePath A path (or a file name) which can end with an archive extension
 * @return The path without the trailing archive extension, or the very same path if it has no such extension
 */
[[nodiscard]] std::filesystem::path BmnCompressionRemoveArchiveExtension(std::filesystem::path aFilePath);
 
#endif   // BmnCompressionGlobalFunctions_h