zipios_FileCollection man page

zipios::FileCollection — Base class for various file collections.

Synopsis

#include <filecollection.hpp>

Inherited by zipios::CollectionCollection, zipios::DirectoryCollection, and zipios::ZipFile.

Public Types

enum MatchPath : uint32_t { MatchPath::IGNORE, MatchPath::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

FileCollection (std::string const &filename='')
Initializes a FileCollection object.
FileCollection (FileCollection const &src)
Copy a FileCollection in a new one.
virtual ~FileCollection ()
Make sure the resources are released.
virtual void addEntry (FileEntry const &entry)
Add an entry to this collection.
virtual pointer_t clone () const =0
Create a clone of this object.
virtual void close ()
Close the current FileEntry of this FileCollection.
virtual FileEntry::vector_t entries () const
Retrieve the array of entries.
virtual FileEntry::pointer_t getEntry (std::string const &name, MatchPath matchpath=MatchPath::MATCH) const
Get an entry from this collection.
virtual stream_pointer_t getInputStream (std::string const &entry_name, MatchPath matchpath=MatchPath::MATCH)=0
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.
FileCollection & operator= (FileCollection const &src)
Replace the content of a collection with a copy of another collection.
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
Returns the number of entries in the FileCollection.

Protected Attributes

FileEntry::vector_t m_entries

std::string m_filename

bool m_valid = true

Detailed Description

FileCollection is an abstract baseclass that represents a collection of files. The specializations of FileCollection represents different origins of file collections, such as directories, simple filename lists and compressed archives.

Definition at line 40 of file filecollection.hpp.

Member Typedef Documentation

typedef std::shared_ptr<FileCollection> zipios::FileCollection::pointer_t

Definition at line 43 of file filecollection.hpp.

std::shared_ptr< std::istream > zipios::FileCollection::stream_pointer_t

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

Definition at line 44 of file filecollection.hpp.

Member Enumeration Documentation

enum zipios::FileCollection::MatchPath : uint32_t [strong]

Enumerator

IGNORE

MATCH

Definition at line 47 of file filecollection.hpp.

Constructor & Destructor Documentation

zipios::FileCollection::FileCollection (std::string const & filename = '')

This FileCollection constructor initializes the object and mark it as invalid. In most cases an invalid collection cannot be used for anything. You may make it valid by copying a valid collection in it.

By default the FileCollection is given the special filename '-'.

The collection is empty and marked as invalid.

Definition at line 269 of file filecollection.cpp.

zipios::FileCollection::FileCollection (FileCollection const & src)

This constructor copies a file collection (src) in a new collection.

The copy entries that all the entries from the source collection get cloned in the copy. This means entries in the source or new collection can be modified and it has no effect on the entries in the other collection.

Parameters:

src The source collection to copy in this collection.

Definition at line 288 of file filecollection.cpp.

References m_entries.

zipios::FileCollection::~FileCollection () [virtual]

The FileCollection destructor makes sure that any resources still allocated get released.

For example, the ZipFile implementation calls the close() function.

Note:

Note that the entries generally get released when this destructor is called. However, since we are using shared pointers, you may still hold valid pointers to the entries even after the FileCollection destructor was called.

Definition at line 349 of file filecollection.cpp.

Member Function Documentation

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

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 368 of file filecollection.cpp.

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

FileCollection::pointer_t zipios::FileCollection::clone () const [pure virtual]

This function creates a heap allocated clone of the object this method is called for.

Returns:

A shared pointer to a copy of the object this method is called for.

Implemented in zipios::ZipFile, zipios::DirectoryCollection, and zipios::CollectionCollection.

Referenced by zipios::CollectionCollection::addCollection().

void zipios::FileCollection::close () [virtual]

This function closes the current file entry.

Reimplemented in zipios::CollectionCollection, and zipios::DirectoryCollection.

Definition at line 378 of file filecollection.cpp.

References zipios::anonymous_namespace{filecollection.cpp}::g_default_filename, m_entries, m_filename, and m_valid.

Referenced by zipios::DirectoryCollection::close(), zipios::CollectionCollection::close(), and zipios::ZipFile::~ZipFile().

FileEntry::vector_t zipios::FileCollection::entries () const [virtual]

This function returns a copy of the file collection vector of entries. Note that the vector is copied but not the entries, so modifications to the entries will be reflected in this FileCollection entries. However, adding and removing entries to the collection is not reflected in the copy.

Returns:

A vector containing the entries of this FileCollection.

Reimplemented in zipios::CollectionCollection, and zipios::DirectoryCollection.

Definition at line 396 of file filecollection.cpp.

References m_entries, and mustBeValid().

Referenced by zipios::DirectoryCollection::entries(), getEntry(), main(), zipios::operator<<(), zipios::ZipFile::saveCollectionToArchive(), setLevel(), setMethod(), and size().

FileEntry::pointer_t zipios::FileCollection::getEntry (std::string const & name, MatchPath matchpath = MatchPath::MATCH) const [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::IGNORE as the second argument.

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 Speficy 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 in zipios::CollectionCollection, and zipios::DirectoryCollection.

Definition at line 424 of file filecollection.cpp.

References entries(), m_entries, MATCH, and mustBeValid().

Referenced by zipios::DirectoryCollection::getEntry(), zipios::ZipFile::getInputStream(), and main().

stream_pointer_t zipios::FileCollection::getInputStream (std::string const & entry_name, MatchPath matchpath = MatchPath::MATCH) [pure 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 FileCollection.

Note that the function returns a smart pointer to an istream. In general the FileCollection will not hold 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.

Warning:

In version 1.0 there was a version of the function accepting a FileEntry instead of a filename. That function was simply calling this function with file_entry->getName() and MatchPath::MATCH so you can convert the call with:

// old code:
ConstEntryPointer ent = zf.getEntry("file2.txt", FileCollection::IGNORE);
if(ent)
{
    auto_ptr<istream> is(getInputStream(ent));
    if(is)
    {
        // got access to the file in the archive
        ...
    }
}

// new code:
zipios::FileEntry::pointer_t ent(zf.getEntry(argv[2], zipios::FileCollection::MatchPath::IGNORE));
if(ent)
{
    zipios::ZipFile::stream_pointer_t is(zf.getInputStream(ent->getName()));
    if(is)
    {
        // got access to the file in the archive
        ...
    }
}

There are two reasons for the change: (1) the function really just called the other with getName() and thus there was no reason to have two functions; and (2) the function did NOT test whether the entry was one that this collection owned making it feel like you could call the getInputStream() function of collection A with entry of collection B and still get a valid stream.

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:

CollectionCollection

DirectoryCollection

ZipFile

Implemented in zipios::ZipFile, zipios::CollectionCollection, and zipios::DirectoryCollection.

Referenced by zipios::ZipFile::saveCollectionToArchive().

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

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 456 of file filecollection.cpp.

References m_filename, and mustBeValid().

Referenced by zipios::operator<<().

bool zipios::FileCollection::isValid () const

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 493 of file filecollection.cpp.

References m_valid.

Referenced by zipios::CollectionCollection::addCollection().

void zipios::FileCollection::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 in zipios::CollectionCollection.

Definition at line 509 of file filecollection.cpp.

References m_valid.

Referenced by entries(), getEntry(), zipios::ZipFile::getInputStream(), getName(), zipios::DirectoryCollection::loadEntries(), zipios::CollectionCollection::mustBeValid(), setLevel(), setMethod(), and size().

FileCollection & zipios::FileCollection::operator= (FileCollection const & rhs)

This function copies the rhs collection in this collection.

Note that the entries in the this collection get released. If you still have a reference to them in a shared pointer, they will not be deleted.

The entries in rhs get cloned so modifying the entries in the source or the destination has no effect on the entries of the other collection.

Parameters:

rhs The source FileCollection to copy.

Returns:

A reference to this FileCollection object.

Definition at line 315 of file filecollection.cpp.

References m_entries, m_filename, and m_valid.

Referenced by zipios::CollectionCollection::operator=().

void zipios::FileCollection::setLevel (size_t limit, FileEntry::CompressionLevel small_compression_level, FileEntry::CompressionLevel large_compression_level)

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.

Definition at line 567 of file filecollection.cpp.

References entries(), m_entries, and mustBeValid().

void zipios::FileCollection::setMethod (size_t limit, StorageMethod small_storage_method, StorageMethod large_storage_method)

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.

Definition at line 532 of file filecollection.cpp.

References entries(), m_entries, and mustBeValid().

size_t zipios::FileCollection::size () const [virtual]

This function returns the number of entries in the collection.

Note:

The collection my be valid.

Returns:

The number of entries in the FileCollection.

See also:

mustBeValid()

Reimplemented in zipios::CollectionCollection.

Definition at line 474 of file filecollection.cpp.

References entries(), m_entries, and mustBeValid().

Referenced by main().

Member Data Documentation

FileEntry::vector_t zipios::FileCollection::m_entries [protected]

Definition at line 73 of file filecollection.hpp.

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

std::string zipios::FileCollection::m_filename [protected]

Definition at line 72 of file filecollection.hpp.

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

bool zipios::FileCollection::m_valid = true [protected]

Definition at line 74 of file filecollection.hpp.

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

Author

Generated automatically by Doxygen for zipios from the source code.

Info

Mon Apr 11 2016 Version 2.1.1 zipios