The BitInputArchive class, given a handler object, allows reading/extracting the content of archives. More...

#include <bit7z/bitinputarchive.hpp>

Inheritance diagram for BitInputArchive:

Classes
class	ConstIterator
	An iterator for the elements contained in an archive. More...

Public Member Functions
	BitInputArchive (const BitAbstractArchiveHandler &handler, const bit7zfs::path &arcPath, ArchiveStartOffset startOffset=ArchiveStartOffset::None)
	Constructs a BitInputArchive object, opening the input file archive.
	BitInputArchive (const BitAbstractArchiveHandler &handler, const buffer_t &inBuffer, ArchiveStartOffset startOffset=ArchiveStartOffset::None)
	Constructs a BitInputArchive object, opening the archive given in the input buffer.
	BitInputArchive (const BitAbstractArchiveHandler &handler, const tstring &inFile, ArchiveStartOffset startOffset=ArchiveStartOffset::None)
	Constructs a BitInputArchive object, opening the input file archive.
	BitInputArchive (const BitAbstractArchiveHandler &handler, std::istream &inStream, ArchiveStartOffset startOffset=ArchiveStartOffset::None)
	Constructs a BitInputArchive object, opening the archive by reading the given input stream.
auto	archiveHasPath () const noexcept -> bool
auto	archivePath () const noexcept -> const tstring &
auto	archiveProperty (BitProperty property) const -> BitPropVariant
	Gets the specified archive property.
auto	begin () const noexcept -> BitInputArchive::ConstIterator
auto	cbegin () const noexcept -> BitInputArchive::ConstIterator
auto	cend () const noexcept -> BitInputArchive::ConstIterator
auto	contains (const tstring &path) const noexcept -> bool
	Find if there is an item in the archive that has the given path.
auto	detectedFormat () const noexcept -> const BitInFormat &
auto	end () const noexcept -> BitInputArchive::ConstIterator
void	extractFolderTo (const tstring &outDir, const tstring &folderPath, FolderPathPolicy policy=FolderPathPolicy::Strip) const
	Extracts a folder from the archive to the chosen directory.
void	extractMatchingRegexTo (buffer_t &outBuffer, const tstring &regex, FilterPolicy policy=FilterPolicy::Include) const
	Extracts to the output buffer the first file in the archive that matches the given regex pattern.
void	extractMatchingRegexTo (const tstring &outDir, const tstring &regex, FilterPolicy policy=FilterPolicy::Include) const
	Extracts to the output directory all the items whose paths match the given regex pattern.
void	extractMatchingTo (buffer_t &outBuffer, const tregex &regex, FilterPolicy policy=FilterPolicy::Include) const
	Extracts to the output buffer the first file in the archive that matches the given regex pattern.
void	extractMatchingTo (buffer_t &outBuffer, const tstring &itemFilter, FilterPolicy policy=FilterPolicy::Include) const
	Extracts to the output buffer the first file whose path matches the given wildcard pattern.
void	extractMatchingTo (const tstring &outDir, const tregex &regex, FilterPolicy policy=FilterPolicy::Include) const
	Extracts to the output directory all the items whose paths match the given regex pattern.
void	extractMatchingTo (const tstring &outDir, const tstring &itemFilter, FilterPolicy policy=FilterPolicy::Include) const
	Extracts to the output directory all the items whose paths match the given wildcard pattern.
void	extractRootFolderContentTo (const tstring &outDir) const
	Extracts the content of the archive's root folder to the chosen directory.
void	extractTo (buffer_t &outBuffer, FilterCallback filterCallback) const
	Extracts to the output buffer the first item satisfying the given filtering criteria.
void	extractTo (buffer_t &outBuffer, std::uint32_t index=0) const
	Extracts a file to the output buffer.
void	extractTo (BufferCallback callback, BitIndicesView indices={}) const
	Extracts the content of the archive to the buffers provided by the given BufferCallback.
void	extractTo (byte_t *outBuffer, std::size_t size, std::uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.
template<std::size_t N>
void	extractTo (byte_t(&outBuffer)[N], std::uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.
void	extractTo (const tstring &outDir, BitIndicesView indices={}) const
	Extracts the specified items to the chosen directory.
void	extractTo (const tstring &outDir, FilterCallback filterCallback) const
	Extracts to the output directory all the items that satisfy the given filtering criteria.
void	extractTo (const tstring &outDir, RenameCallback renameCallback) const
	Extracts the archive to the chosen directory, specifying the names of the extracted items via a RenameCallback.
void	extractTo (RawDataCallback callback, BitIndicesView indices={}) const
	Extracts the raw content of the archive to the given callback.
template<std::size_t N>
void	extractTo (std::array< byte_t, N > &outBuffer, std::uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.
void	extractTo (std::map< tstring, buffer_t > &outMap) const
	Extracts the content of the archive to a map of memory buffers, where the keys are the paths of the files (inside the archive), and the values are their decompressed contents.
void	extractTo (std::ostream &outStream, std::uint32_t index=0) const
	Extracts a file to the output stream.
auto	find (const tstring &path) const noexcept -> BitInputArchive::ConstIterator
	Find an item in the archive that has the given path.
auto	findByName (const tstring &name) const noexcept -> BitInputArchive::ConstIterator
	Find an item in the archive that has the given name (last component of its path within the archive).
auto	handler () const noexcept -> const BitAbstractArchiveHandler &
auto	isItemEncrypted (std::uint32_t index) const -> bool
auto	isItemFolder (std::uint32_t index) const -> bool
auto	itemAt (std::uint32_t index) const -> BitArchiveItemOffset
	Retrieve the item at the given index.
auto	itemHasProperty (std::uint32_t index, BitProperty property) const -> bool
	Checks whether the item at the given index has the specified property.
auto	itemProperty (std::uint32_t index, BitProperty property) const -> BitPropVariant
	Gets the specified property of an item in the archive.
auto	itemsCount () const -> std::uint32_t
auto	mainSubfileIndex () const -> std::uint32_t
auto	rootFolder () const -> tstring
	Returns the single top-level folder that contains all of the archive's items.
void	test (BitIndicesView indices={}) const
	Tests the archive without extracting its content.
void	testItem (std::uint32_t index) const
	Tests the archive item at the given index without extracting it.
void	useFormatProperty (const wchar_t *name, const BitPropVariant &property) const
	Use the given format property to read the archive.
template<typename T, typename = typename std::enable_if< is_explicitly_convertible< T, BitPropVariant >::value >::type>
void	useFormatProperty (const wchar_t *name, T &&value) const
	Use the given format property to read the archive.

Detailed Description

The BitInputArchive class, given a handler object, allows reading/extracting the content of archives.

Constructor & Destructor Documentation

◆ BitInputArchive() [1/4]

BitInputArchive	(	const BitAbstractArchiveHandler &	handler,
		const tstring &	inFile,
		ArchiveStartOffset	startOffset = ArchiveStartOffset::None )

Constructs a BitInputArchive object, opening the input file archive.

Parameters

handler	the reference to the BitAbstractArchiveHandler object containing all the settings to be used for reading the input archive
inFile	the path to the input archive file
startOffset	(optional) specifies whether to search for the archive's start throughout the entire file or only at the beginning. The default behavior is to search at the beginning.

◆ BitInputArchive() [2/4]

BitInputArchive	(	const BitAbstractArchiveHandler &	handler,
		const bit7zfs::path &	arcPath,
		ArchiveStartOffset	startOffset = ArchiveStartOffset::None )

Constructs a BitInputArchive object, opening the input file archive.

Parameters

handler	the reference to the BitAbstractArchiveHandler object containing all the settings to be used for reading the input archive
arcPath	the path to the input archive file
startOffset	(optional) whether to search for the archive's start throughout the entire file or only at the beginning. The default behavior is to search at the beginning.

◆ BitInputArchive() [3/4]

BitInputArchive	(	const BitAbstractArchiveHandler &	handler,
		const buffer_t &	inBuffer,
		ArchiveStartOffset	startOffset = ArchiveStartOffset::None )

Constructs a BitInputArchive object, opening the archive given in the input buffer.

Parameters

handler	the reference to the BitAbstractArchiveHandler object containing all the settings to be used for reading the input archive
inBuffer	the buffer containing the input archive
startOffset	(optional) whether to search for the archive's start throughout the entire file or only at the beginning. The default behavior is to search at the beginning.

◆ BitInputArchive() [4/4]

BitInputArchive	(	const BitAbstractArchiveHandler &	handler,
		std::istream &	inStream,
		ArchiveStartOffset	startOffset = ArchiveStartOffset::None )

Constructs a BitInputArchive object, opening the archive by reading the given input stream.

Parameters

handler	the reference to the BitAbstractArchiveHandler object containing all the settings to be used for reading the input archive
inStream	the standard input stream of the input archive
startOffset	(optional) whether to search for the archive's start throughout the entire file or only at the beginning. The default behavior is to search at the beginning.

Member Function Documentation

◆ archiveHasPath()

auto archiveHasPath ( ) const -> bool

noexcept

Returns: whether the archive has a path (i.e., filesystem archive), or not (e.g., buffer archive).

◆ archivePath()

auto archivePath ( ) const -> const tstring &

noexcept

Returns: the path to the archive (the empty string for buffer/stream archives).

◆ archiveProperty()

auto archiveProperty ( BitProperty property ) const -> BitPropVariant

Gets the specified archive property.

Parameters

property the property to be retrieved.

Returns: the current value of the archive property or an empty BitPropVariant if no value is specified.

◆ begin()

auto begin ( ) const -> BitInputArchive::ConstIterator

noexcept

Returns: an iterator to the first element of the archive; if the archive is empty, the returned iterator will be equal to the end() iterator.

◆ cbegin()

auto cbegin ( ) const -> BitInputArchive::ConstIterator

noexcept

Returns: an iterator to the first element of the archive; if the archive is empty, the returned iterator will be equal to the end() iterator.

◆ cend()

auto cend ( ) const -> BitInputArchive::ConstIterator

noexcept

Returns: an iterator to the element following the last element of the archive; this element acts as a placeholder: attempting to access it results in undefined behavior.

◆ contains()

auto contains ( const tstring & path ) const -> bool

noexcept

Find if there is an item in the archive that has the given path.

Parameters

path	the path to be searched in the archive.

Returns: true if and only if an item with the given path exists in the archive.

◆ detectedFormat()

auto detectedFormat ( ) const -> const BitInFormat &

noexcept

Returns: the detected format of the file.

◆ end()

auto end ( ) const -> BitInputArchive::ConstIterator

noexcept

Returns: an iterator to the element following the last element of the archive; this element acts as a placeholder: attempting to access it results in undefined behavior.

◆ extractFolderTo()

void extractFolderTo	(	const tstring &	outDir,
		const tstring &	folderPath,
		FolderPathPolicy	policy = FolderPathPolicy::Strip ) const

Extracts a folder from the archive to the chosen directory.

Parameters

outDir	the output directory where the extracted folder will be put.
folderPath	the path of the folder inside the archive to be extracted.
policy	(optional) the path policy to be used for extracting the folder.

◆ extractMatchingRegexTo() [1/2]

void extractMatchingRegexTo	(	buffer_t &	outBuffer,
		const tstring &	regex,
		FilterPolicy	policy = FilterPolicy::Include ) const

Extracts to the output buffer the first file in the archive that matches the given regex pattern.

Note: Available only when compiling bit7z using the BIT7Z_REGEX_MATCHING preprocessor define.

Parameters

outBuffer	the output buffer where the extracted file will be put.
regex	the regex used for matching the paths of files inside the archive.
policy	(optional) the filtering policy to be applied to the matched items.

◆ extractMatchingRegexTo() [2/2]

void extractMatchingRegexTo	(	const tstring &	outDir,
		const tstring &	regex,
		FilterPolicy	policy = FilterPolicy::Include ) const

Extracts to the output directory all the items whose paths match the given regex pattern.

Note: Available only when compiling bit7z using the BIT7Z_REGEX_MATCHING preprocessor define.

Parameters

outDir	the output directory where extracted files will be put.
regex	the regex used for matching the paths of files inside the archive.
policy	(optional) the filtering policy to be applied to the matching items.

◆ extractMatchingTo() [1/4]

void extractMatchingTo	(	buffer_t &	outBuffer,
		const tregex &	regex,
		FilterPolicy	policy = FilterPolicy::Include ) const

Extracts to the output buffer the first file in the archive that matches the given regex pattern.

Note: Available only when compiling bit7z using the BIT7Z_REGEX_MATCHING preprocessor define.

Parameters

outBuffer	the output buffer where the extracted file will be put.
regex	the regex used for matching the paths of files inside the archive.
policy	(optional) the filtering policy to be applied to the matched items.

◆ extractMatchingTo() [2/4]

void extractMatchingTo	(	buffer_t &	outBuffer,
		const tstring &	itemFilter,
		FilterPolicy	policy = FilterPolicy::Include ) const

Extracts to the output buffer the first file whose path matches the given wildcard pattern.

Parameters

outBuffer	the output buffer where to extract the file.
itemFilter	the wildcard pattern used for matching the paths of files inside the archive.
policy	(optional) the filtering policy to be applied to the matched items.

◆ extractMatchingTo() [3/4]

void extractMatchingTo	(	const tstring &	outDir,
		const tregex &	regex,
		FilterPolicy	policy = FilterPolicy::Include ) const

Extracts to the output directory all the items whose paths match the given regex pattern.

Note: Available only when compiling bit7z using the BIT7Z_REGEX_MATCHING preprocessor define.

Parameters

outDir	the output directory where extracted files will be put.
regex	the regex used for matching the paths of files inside the archive.
policy	(optional) the filtering policy to be applied to the matching items.

◆ extractMatchingTo() [4/4]

void extractMatchingTo	(	const tstring &	outDir,
		const tstring &	itemFilter,
		FilterPolicy	policy = FilterPolicy::Include ) const

Extracts to the output directory all the items whose paths match the given wildcard pattern.

Parameters

outDir	the output directory where extracted files will be put.
itemFilter	the wildcard pattern used for matching the paths of items inside the archive.
policy	(optional) the filtering policy to be applied to the matching items.

◆ extractRootFolderContentTo()

void extractRootFolderContentTo ( const tstring & outDir ) const

Extracts the content of the archive's root folder to the chosen directory.

The archive's root folder is the single top-level folder shared by all the items in the archive; its name is stripped from the extracted items' paths.

Note: If the archive does not have a single root folder, a BitException is thrown.

Parameters

outDir the output directory where the root folder's content will be put.

◆ extractTo() [1/12]

void extractTo	(	buffer_t &	outBuffer,
		FilterCallback	filterCallback ) const

Extracts to the output buffer the first item satisfying the given filtering criteria.

Parameters

outBuffer	the output buffer where the extracted file will be put.
filterCallback	the filtering callback that specifies whether to extract an item or not.

◆ extractTo() [2/12]

void extractTo	(	buffer_t &	outBuffer,
		std::uint32_t	index = 0 ) const

Extracts a file to the output buffer.

Parameters

outBuffer	the output buffer where the content of the archive will be put.
index	(optional) the index of the file to be extracted.

◆ extractTo() [3/12]

void extractTo	(	BufferCallback	callback,
		BitIndicesView	indices = {} ) const

Extracts the content of the archive to the buffers provided by the given BufferCallback.

Parameters

callback	the function providing the buffers.
indices	(optional) the indices of the files in the archive that must be extracted.

◆ extractTo() [4/12]

void extractTo	(	byte_t *	outBuffer,
		std::size_t	size,
		std::uint32_t	index = 0 ) const

Extracts a file to the pre-allocated output buffer.

Parameters

outBuffer	the pre-allocated output buffer.
size	the size of the output buffer (it must be equal to the unpacked size of the item to be extracted).
index	the index of the file to be extracted.

◆ extractTo() [5/12]

template<std::size_t N>

void extractTo	(	byte_t(&)	outBuffer[N],
		std::uint32_t	index = 0 ) const

inline

Extracts a file to the pre-allocated output buffer.

Template Parameters

N	the size of the output buffer (it must be equal to the unpacked size of the item to be extracted).

Parameters

outBuffer	the pre-allocated output buffer.
index	the index of the file to be extracted.

◆ extractTo() [6/12]

void extractTo	(	const tstring &	outDir,
		BitIndicesView	indices = {} ) const

Extracts the specified items to the chosen directory.

Parameters

outDir	the output directory where the extracted files will be put.
indices	(optional) the indices of the files in the archive that must be extracted.

◆ extractTo() [7/12]

void extractTo	(	const tstring &	outDir,
		FilterCallback	filterCallback ) const

Extracts to the output directory all the items that satisfy the given filtering criteria.

Parameters

outDir	the output directory where extracted files will be put.
filterCallback	the filtering callback that specifies whether to extract an item or not.

◆ extractTo() [8/12]

void extractTo	(	const tstring &	outDir,
		RenameCallback	renameCallback ) const

Extracts the archive to the chosen directory, specifying the names of the extracted items via a RenameCallback.

Note: The callback receives the archive item being extracted and must return the path that the extracted item must have on the filesystem. If the path of the item must not change, simply return the item's path in the callback. If the item must not be extracted, return an empty string in the callback.

Parameters

outDir	the output directory where the extracted files will be put.
renameCallback	the callback that returns the names for the extracted files.

◆ extractTo() [9/12]

void extractTo	(	RawDataCallback	callback,
		BitIndicesView	indices = {} ) const

Extracts the raw content of the archive to the given callback.

Note: You can set a FileCallback to check the file being extracted.

Parameters

callback	a function providing the extracted raw data to the user.
indices	(optional) the indices of the files in the archive that must be extracted.

◆ extractTo() [10/12]

template<std::size_t N>

void extractTo	(	std::array< byte_t, N > &	outBuffer,
		std::uint32_t	index = 0 ) const

inline

Extracts a file to the pre-allocated output buffer.

Template Parameters

N	the size of the output buffer (it must be equal to the unpacked size of the item to be extracted).

Parameters

outBuffer	the pre-allocated output buffer.
index	the index of the file to be extracted.

◆ extractTo() [11/12]

void extractTo ( std::map< tstring, buffer_t > & outMap ) const

Extracts the content of the archive to a map of memory buffers, where the keys are the paths of the files (inside the archive), and the values are their decompressed contents.

Parameters

outMap the output map.

◆ extractTo() [12/12]

void extractTo	(	std::ostream &	outStream,
		std::uint32_t	index = 0 ) const

Extracts a file to the output stream.

Parameters

outStream	the (binary) stream where the content of the archive will be put.
index	the index of the file to be extracted.

◆ find()

auto find ( const tstring & path ) const -> BitInputArchive::ConstIterator

noexcept

Find an item in the archive that has the given path.

Parameters

path	the path to be searched in the archive.

Returns: an iterator to the item with the given path, or an iterator equal to the end() iterator if no item is found.

◆ findByName()

auto findByName ( const tstring & name ) const -> BitInputArchive::ConstIterator

noexcept

Find an item in the archive that has the given name (last component of its path within the archive).

Parameters

name	the name to be searched in the archive.

Returns: an iterator to the item with the given name, or an iterator equal to the end() iterator if no item is found.

◆ handler()

auto handler ( ) const -> const BitAbstractArchiveHandler &

noexcept

Returns: the BitAbstractArchiveHandler object containing the settings for reading the archive.

◆ isItemEncrypted()

auto isItemEncrypted ( std::uint32_t index ) const -> bool

Parameters

index the index of an item in the archive.

Returns: true if and only if the item at the given index is encrypted.

◆ isItemFolder()

auto isItemFolder ( std::uint32_t index ) const -> bool

Parameters

index the index of an item in the archive.

Returns: true if and only if the item at the given index is a folder.

◆ itemAt()

auto itemAt ( std::uint32_t index ) const -> BitArchiveItemOffset

Retrieve the item at the given index.

Parameters

index the index of the item to be retrieved.

Returns: the item at the given index within the archive.

◆ itemHasProperty()

auto itemHasProperty	(	std::uint32_t	index,
		BitProperty	property ) const -> bool

Checks whether the item at the given index has the specified property.

Parameters

index	the index (in the archive) of the item.
property	the property to be checked for existence.

Returns: true if the item has the property, false otherwise.

◆ itemProperty()

auto itemProperty	(	std::uint32_t	index,
		BitProperty	property ) const -> BitPropVariant

Gets the specified property of an item in the archive.

Parameters

index	the index (in the archive) of the item.
property	the property to be retrieved.

Returns: the current value of the item property or an empty BitPropVariant if the item has no value for the property.

◆ itemsCount()

auto itemsCount ( ) const -> std::uint32_t

Returns: the number of items contained in the archive.

◆ mainSubfileIndex()

auto mainSubfileIndex ( ) const -> std::uint32_t

Returns: the index of the main subfile of the archive, if any.

Exceptions

BitException if the archive format doesn't have a main subfile.

◆ rootFolder()

auto rootFolder ( ) const -> tstring

Returns the single top-level folder that contains all of the archive's items.

The archive is considered to have a root folder only when every item is contained within the same top-level folder. There is no common root folder if the items belong to different top-level folders, if the archive contains a file at its root, or if the archive is empty.

Note: The returned value is the folder's name, without any trailing path separator.

Returns: the name of the archive's root folder, or an empty string if the archive does not have a single common root folder.

◆ test()

void test ( BitIndicesView indices = {} ) const

Tests the archive without extracting its content.

Parameters

indices (optional) the indices of the items to be tested.

Exceptions

BitException if the archive is not valid.

◆ testItem()

void testItem ( std::uint32_t index ) const

Tests the archive item at the given index without extracting it.

Parameters

index the index of the item to be tested.

Exceptions

BitException if the index is not valid, or the item at the given index is not valid, or the whole archive is not valid.

◆ useFormatProperty() [1/2]

void useFormatProperty	(	const wchar_t *	name,
		const BitPropVariant &	property ) const

Use the given format property to read the archive.

Parameters

name	the name of the property.
property	the property value.

◆ useFormatProperty() [2/2]

template<typename T, typename = typename std::enable_if< is_explicitly_convertible< T, BitPropVariant >::value >::type>

void useFormatProperty	(	const wchar_t *	name,
		T &&	value ) const

inline

Use the given format property to read the archive.

Template Parameters

T	the type of the property.

Parameters

name	the name of the property.
value	the property value.

The documentation for this class was generated from the following file:

include/bit7z/bitinputarchive.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BitInputArchive() [1/4]

◆ BitInputArchive() [2/4]

◆ BitInputArchive() [3/4]

◆ BitInputArchive() [4/4]

Member Function Documentation

◆ archiveHasPath()

◆ archivePath()

◆ archiveProperty()

◆ begin()

◆ cbegin()

◆ cend()

◆ contains()

◆ detectedFormat()

◆ end()

◆ extractFolderTo()

◆ extractMatchingRegexTo() [1/2]

◆ extractMatchingRegexTo() [2/2]

◆ extractMatchingTo() [1/4]

◆ extractMatchingTo() [2/4]

◆ extractMatchingTo() [3/4]

◆ extractMatchingTo() [4/4]

◆ extractRootFolderContentTo()

◆ extractTo() [1/12]

◆ extractTo() [2/12]

◆ extractTo() [3/12]

◆ extractTo() [4/12]

◆ extractTo() [5/12]

◆ extractTo() [6/12]

◆ extractTo() [7/12]

◆ extractTo() [8/12]

◆ extractTo() [9/12]

◆ extractTo() [10/12]

◆ extractTo() [11/12]

◆ extractTo() [12/12]

◆ find()

◆ findByName()

◆ handler()

◆ isItemEncrypted()

◆ isItemFolder()

◆ itemAt()

◆ itemHasProperty()

◆ itemProperty()

◆ itemsCount()

◆ mainSubfileIndex()

◆ rootFolder()

◆ test()

◆ testItem()

◆ useFormatProperty() [1/2]

◆ useFormatProperty() [2/2]