zipios::CollectionCollection(3)

zipios

zipios::CollectionCollection(3)

NAME¶

zipios::CollectionCollection - A collection of collections.

SYNOPSIS¶

#include <collectioncollection.hpp>

Inherits zipios::FileCollection.

Public Types¶

enum class MatchPath : uint32_t { IGNORE, MATCH }
typedef std::shared_ptr< FileCollection > pointer_t
typedef std::shared_ptr< std::istream > stream_pointer_t
A shared pointer to an input stream. typedef std::vector< pointer_t > vector_t

Public Member Functions¶

CollectionCollection ()
Initialize a CollectionCollection object. CollectionCollection (CollectionCollection const &rhs)
Copy a CollectionCollection in another. virtual ~CollectionCollection () override
Clean up this CollectionCollection object. bool addCollection (FileCollection const &collection)
Add a FileCollection to this CollectionCollection. bool addCollection (FileCollection::pointer_t collection)
Add a collection to this CollectionCollection. virtual void addEntry (FileEntry const &entry)
Add an entry to this collection. virtual pointer_t clone () const override
Create a clone of this object. virtual void close () override
Close the CollectionCollection object. virtual FileEntry::vector_t entries () const override
Retrieve a vector to all the collection entries. virtual FileEntry::pointer_t getEntry (std::string const &name, MatchPath matchpath=MatchPath::MATCH) const override
Get an entry from the collection. virtual stream_pointer_t getInputStream (std::string const &entry_name, MatchPath matchpath=MatchPath::MATCH) override
Retrieve pointer to an istream. virtual std::string getName () const
Returns the name of the FileCollection. bool isValid () const
Check whether the current collection is valid. virtual void mustBeValid () const
Check whether the collection is valid. CollectionCollection & operator= (CollectionCollection const &rhs)
Copy assignment operator. void setLevel (size_t limit, FileEntry::CompressionLevel small_compression_level, FileEntry::CompressionLevel large_compression_level)
Change the compression level to the specified value. void setMethod (size_t limit, StorageMethod small_storage_method, StorageMethod large_storage_method)
Change the storage method to the specified value. virtual size_t size () const override
Return the size of the of this collection.

Protected Attributes¶

vector_t m_collections
FileEntry::vector_t m_entries = FileEntry::vector_t()
std::string m_filename = std::string()
bool m_valid = true

Detailed Description¶

CollectionCollection is a FileCollection that consists of an arbitrary number of FileCollection's. With a CollectionCollection the user can use multiple FileCollection objects transparently, making it easy for a program to keep some of its files in a zip archive and others stored in ordinary files. CollectionCollection can be used to create a simple virtual filesystem, where all collections are mounted on /. If more than one collection contain a file with the same path only the one in the first added collection is accessible.

Definition at line 40 of file collectioncollection.hpp.

Member Typedef Documentation¶

typedef std::shared_ptr<FileCollection> zipios::FileCollection::pointer_t [inherited]¶

Definition at line 43 of file filecollection.hpp.

std::shared_ptr< std::istream > zipios::FileCollection::stream_pointer_t [inherited]¶

This type of pointer is used whenever you retrieve an input stream from a file collection such as the ZipFile class. Having shared pointers ensures that the pointers can be shared between various functions and it gets deleted in the end.

Definition at line 45 of file filecollection.hpp.

typedef std::vector<pointer_t> zipios::FileCollection::vector_t [inherited]¶

Definition at line 44 of file filecollection.hpp.

Member Enumeration Documentation¶

enum class zipios::FileCollection::MatchPath : uint32_t [strong], [inherited]¶

Enumerator

IGNORE
MATCH

Definition at line 47 of file filecollection.hpp.

Constructor & Destructor Documentation¶

zipios::CollectionCollection::CollectionCollection () [explicit]¶

The constructor initializes the CollectionCollection as a valid collection.

Definition at line 102 of file collectioncollection.cpp.

References zipios::FileCollection::m_valid.

zipios::CollectionCollection::CollectionCollection (CollectionCollection const & rhs)¶

This function copies a collection of collections in another. Note that all the children get cloned so the copy can be edited without modify the source and vice versa.

Parameters

rhs The source to copy in the new CollectionCollection.

Definition at line 116 of file collectioncollection.cpp.

References m_collections.

zipios::CollectionCollection::~CollectionCollection () [override], [virtual]¶

This function ensures that the CollectionCollection object is cleaned up before deallocating the memory.

Definition at line 177 of file collectioncollection.cpp.

References close().

Member Function Documentation¶

bool zipios::CollectionCollection::addCollection (FileCollection const & collection)¶

This function adds a collection in this CollectionCollection. Since a CollectionCollection is itself a FileCollection, you may add a CollectionCollection to another CollectionCollection.

Note

The FileCollection to be added must be valid or it will be ignored.

Parameters

collection The collection to add.

Returns

true if the collection was added successfully.

See also

addCollection(FileCollection::pointer_t collection);

Todo

At this time the function verifies that you are not trying to add a CollectionCollection to itself. However, this test is currently really weak. We need to check whether any collection in the input collection represents this collection.

Definition at line 198 of file collectioncollection.cpp.

References zipios::FileCollection::clone(), zipios::FileCollection::isValid(), m_collections, and mustBeValid().

Referenced by addCollection().

bool zipios::CollectionCollection::addCollection (FileCollection::pointer_t collection)¶

This function adds the collection pointed to by collection to this CollectionCollection.

The CollectionCollection makes a clone of the specified collection to make sure management of the child collection works as expected.

If the collection does not get added, the function returns false. This happens when the collection parameter represents an invalid collection.

Exceptions

InvalidException The function raises InvalidException if the collection parameter is a null pointer.

Parameters

collection A pointer to the collection to add.

Returns

true if the collection was added successfully.

See also

addCollection(FileCollection const & collection);

Definition at line 241 of file collectioncollection.cpp.

References addCollection().

void zipios::FileCollection::addEntry (FileEntry const & entry) [virtual], [inherited]¶

This function adds an entry to the file collection allowing you to create a FileCollection from the exact files you want to have in the collection instead of having to read an entire directory as the DirectoryCollection offers by default.

Warning

This function creates a clone of the entry to make sure that the caller's entry can be modified without affecting the FileCollection.

Parameters

entry The entry to add to the FileCollection.

Definition at line 365 of file filecollection.cpp.

References zipios::FileEntry::clone(), and zipios::FileCollection::m_entries.

FileCollection::pointer_t zipios::CollectionCollection::clone () const [override], [virtual]¶

This function creates a heap allocated clone of the CollectionCollection.

Note that all the collections that this CollectionCollection points to are all going to get cloned.

Returns

A shared pointer to a copy of this CollectionCollection.

Implements zipios::FileCollection.

Definition at line 166 of file collectioncollection.cpp.

void zipios::CollectionCollection::close () [override], [virtual]¶

This function marks the collection as invalid in effect rendering the collection unusable. Note that all the collections that you previously added to this collection all get marked as invalid (i.e. their close() function gets called.) This has the nice side effect to release memory immediately.

Note

This is different from creating an empty CollectionCollection which is empty and valid.

Reimplemented from zipios::FileCollection.

Definition at line 265 of file collectioncollection.cpp.

References zipios::FileCollection::close(), and m_collections.

Referenced by ~CollectionCollection().

FileEntry::vector_t zipios::CollectionCollection::entries () const [override], [virtual]¶

This function gathers the entries of all the children collections and add them to a vector that it then returns.

The CollectionCollection itself has no entries.

It is possible to define a CollectionCollection as a child of another CollectionCollection. The process repeats infinitum as required.

Returns

A copy of all the entries found in the child Collections.

Reimplemented from zipios::FileCollection.

Definition at line 298 of file collectioncollection.cpp.

References m_collections, and mustBeValid().

FileEntry::pointer_t zipios::CollectionCollection::getEntry (std::string const & name, MatchPath matchpath = MatchPath::MATCH) const [override], [virtual]¶

This function returns a shared pointer to a FileEntry object for the entry with the specified name. To ignore the path part of the filename while searching for a match, specify FileCollection::MatchPath::IGNORE as the second argument. (the default is FileCollection::MatchPath::MATCH.

Warning

In case of the CollectionCollection, the matching goes from child collection to child collection in the order they were added to the CollectionCollection. The first match is returned and at this point there is nothing linking a FileEntry to its collection so you will NOT be able to retrieve an istream to access that FileEntry data. To do that, you must directly call the getInputStream() function. We may fix that problem at a later time and offer the getInputStream directly on the FileEntry instead of the collection. This is problematic at this point since, as we can see in the zipfile.cpp, we need to have access to the m_zs offset.

Note

The collection must be valid or the function raises an exception.

Parameters

name A string containing the name of the entry to get.
matchpath Specify MatchPath::MATCH, if the path should match as well, specify MatchPath::IGNORE, if the path should be ignored.

Returns

A shared pointer to the found entry. The returned pointer is null if no entry is found.

See also

mustBeValid()

Reimplemented from zipios::FileCollection.

Definition at line 346 of file collectioncollection.cpp.

References m_collections, and mustBeValid().

CollectionCollection::stream_pointer_t zipios::CollectionCollection::getInputStream (std::string const & entry_name, MatchPath matchpath = MatchPath::MATCH) [override], [virtual]¶

This function returns a shared pointer to an istream defined from the named entry, which is expected to be available in this collection.

The function returns a NULL pointer if there is no entry with the specified name in this CollectionCollection. Note that the name is searched in all the child collections of the CollectionCollection.

Note that the function returns a smart pointer to an istream. In general the CollectionCollection will not hold a copy of that pointer meaning that if you call getInputStream() multiple times with the same entry_name parameter, you get distinct istream instances each time.

By default the entry_name parameter is expected to match the full path and filename (MatchPath::MATCH). If you are looking for a file and want to ignore the directory name, set the matchpath parameter to MatchPath::IGNORE.

Parameters

entry_name The name of the file to search in the collection.
matchpath Whether the full path or just the filename is matched.

Returns

A shared pointer to an open istream for the specified entry.

See also

FileCollection

DirectoryCollection

ZipFile

Implements zipios::FileCollection.

Definition at line 389 of file collectioncollection.cpp.

References m_collections, and mustBeValid().

std::string zipios::FileCollection::getName () const [virtual], [inherited]¶

This function returns the filename of the collection as a whole.

Note

The collection my be valid.

Returns

The name of the FileCollection.

See also

mustBeValid()

Definition at line 453 of file filecollection.cpp.

References zipios::FileCollection::m_filename, and zipios::FileCollection::mustBeValid().

Referenced by zipios::operator<<().

bool zipios::FileCollection::isValid () const [inherited]¶

This function returns true if the collection is valid.

Note that by default (just after a new) a collection is not considered valid.

Returns

true if the collection is valid.

Definition at line 490 of file filecollection.cpp.

References zipios::FileCollection::m_valid.

Referenced by addCollection().

void zipios::CollectionCollection::mustBeValid () const [virtual]¶

This function verifies that the collection is valid. If not, an exception is raised. Many other functions from the various collection functions are calling this function before accessing data.

Exceptions

InvalidStateException This exception is raised if the m_valid field is currently false and thus most of the collection data is considered invalid.

Reimplemented from zipios::FileCollection.

Definition at line 437 of file collectioncollection.cpp.

References m_collections, and zipios::FileCollection::mustBeValid().

Referenced by addCollection(), entries(), getEntry(), getInputStream(), and size().

CollectionCollection & zipios::CollectionCollection::operator= (CollectionCollection const & rhs)¶

This assignment operator copies rhs to this collection replacing the file entries that exist in this collection.

Note that the source file entries are cloned in the destination so modifying this collection will not modify the source.

Parameters

rhs The source to copy in this collection.

Definition at line 137 of file collectioncollection.cpp.

References m_collections, and zipios::FileCollection::operator=().

void zipios::FileCollection::setLevel (size_t limit, FileEntry::CompressionLevel small_compression_level, FileEntry::CompressionLevel large_compression_level) [inherited]¶

This function changes the compression level of all the entries in this collection to the specified value.

The size limit is used to know which compression level to use: small_compression_level for any file that has a size smaller or equal to the specified limit and large_compression_level for the others.

Parameters

limit The threshold to use to define the compression level.
small_compression_level The compression level for smaller files.
large_compression_level The compression level for larger files.

See also

setMethod()

Definition at line 571 of file filecollection.cpp.

References zipios::FileCollection::entries(), zipios::FileCollection::m_entries, and zipios::FileCollection::mustBeValid().

Referenced by main().

void zipios::FileCollection::setMethod (size_t limit, StorageMethod small_storage_method, StorageMethod large_storage_method) [inherited]¶

This function changes the storage method of all the entries in this collection to the specified value.

The size limit is used to know which storage method to use: small_storage_method for any file that has a size smaller or equal to the specified limit and large_storage_method for the others.

Parameters

limit The threshold to use to define the compression level.
small_storage_method The storage method for smaller files.
large_storage_method The storage method for larger files.

See also

setLevel()

Definition at line 531 of file filecollection.cpp.

References zipios::FileCollection::entries(), zipios::FileCollection::m_entries, and zipios::FileCollection::mustBeValid().

Referenced by main().

size_t zipios::CollectionCollection::size () const [override], [virtual]¶

This function computes the total size of this collection which is to sum of the size of its child collections.

Warning

This function has the side effect of loading all the data from DirectoryCollection objects.

Returns

The total size of the collection.

Reimplemented from zipios::FileCollection.

Definition at line 413 of file collectioncollection.cpp.

References m_collections, and mustBeValid().

Member Data Documentation¶

vector_t zipios::CollectionCollection::m_collections [protected]¶

Definition at line 60 of file collectioncollection.hpp.

Referenced by CollectionCollection(), addCollection(), close(), entries(), getEntry(), getInputStream(), mustBeValid(), operator=(), and size().

FileEntry::vector_t zipios::FileCollection::m_entries = FileEntry::vector_t() [protected], [inherited]¶

Definition at line 74 of file filecollection.hpp.

Referenced by zipios::FileCollection::FileCollection(), zipios::FileCollection::addEntry(), zipios::FileCollection::close(), zipios::FileCollection::entries(), zipios::FileCollection::getEntry(), zipios::ZipFile::init(), zipios::DirectoryCollection::load(), zipios::DirectoryCollection::loadEntries(), zipios::FileCollection::operator=(), zipios::FileCollection::setLevel(), zipios::FileCollection::setMethod(), and zipios::FileCollection::size().

std::string zipios::FileCollection::m_filename = std::string() [protected], [inherited]¶

Definition at line 73 of file filecollection.hpp.

Referenced by zipios::DirectoryCollection::DirectoryCollection(), zipios::ZipFile::ZipFile(), zipios::FileCollection::close(), zipios::ZipFile::getInputStream(), zipios::FileCollection::getName(), and zipios::FileCollection::operator=().

bool zipios::FileCollection::m_valid = true [protected], [inherited]¶

Definition at line 75 of file filecollection.hpp.

Referenced by CollectionCollection(), zipios::DirectoryCollection::DirectoryCollection(), zipios::FileCollection::close(), zipios::ZipFile::init(), zipios::FileCollection::isValid(), zipios::FileCollection::mustBeValid(), and zipios::FileCollection::operator=().

Author¶

Generated automatically by Doxygen for zipios from the source code.

Sat Dec 30 2023 01:18:29

Version 2.3.2

Source file:	zipios_CollectionCollection.3.en.gz (from zipios-devel 2.3.2-1.3)
Source last updated:	2023-12-30T01:18:32Z
Converted to HTML:	2024-12-03T01:54:50Z