wxArchiveIterator Class Reference

#include <wx/archive.h>

Detailed Description

An input iterator template class that can be used to transfer an archive's catalogue to a container.

It is only available if wxUSE_STL is set to 1 in setup.h, and the uses for it outlined below require a compiler which supports member templates.

template<class Arc, class T = typename Arc::entry_type*>
class wxArchiveIterator
{
    // this constructor creates an 'end of sequence' object
    wxArchiveIterator();

    // template parameter 'Arc' should be the type of an archive input stream
    wxArchiveIterator(Arc& arc) {
        // ...
    }
};

The first template parameter should be the type of archive input stream (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pair<wxString,wxArchiveEntry*>).

The wx/archive.h header defines the following typedefs:

typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;

typedef wxArchiveIterator<wxArchiveInputStream,
        std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;

The header for any implementation of this interface should define similar typedefs for its types, for example in wx/zipstrm.h there is:

typedef wxArchiveIterator<wxZipInputStream> wxZipIter;

typedef wxArchiveIterator<wxZipInputStream,
         std::pair<wxString, wxZipEntry*> > wxZipPairIter;

Transferring the catalogue of an archive arc to a vector cat, can then be done something like this:

std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());

When the iterator is dereferenced, it gives away ownership of an entry object. So in the above example, when you have finished with cat you must delete the pointers it contains.

If you have smart pointers with normal copy semantics (i.e. not auto_ptr or wxScopedPtr), then you can create an iterator which uses them instead.

For example, with a smart pointer class for zip entries ZipEntryPtr:

typedef std::vector<ZipEntryPtr> ZipCatalog;
typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
ZipCatalog cat((ZipIter)zip, ZipIter());

Iterators that return std::pair objects can be used to populate a std::multimap, to allow entries to be looked up by name. The string is initialised using the wxArchiveEntry object's wxArchiveEntry::GetInternalName function.

typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());

Note that this iterator also gives away ownership of an entry object each time it is dereferenced. So in the above example, when you have finished with cat you must delete the pointers it contains.

Or if you have them, a pair containing a smart pointer can be used (again ZipEntryPtr), no worries about ownership:

typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
typedef wxArchiveIterator<wxZipInputStream,
            std::pair<wxString, ZipEntryPtr> > ZipPairIter;
ZipCatalog cat((ZipPairIter)zip, ZipPairIter());

Library:  wxBase

Category:  Archive support, Streams

See Also

wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream

Public Member Functions
	wxArchiveIterator ()
	Default constructor.
	wxArchiveIterator (Arc &arc)
	Construct the iterator that returns all the entries in the archive input stream arc.
const T	operator* () const
	Returns an entry object from the archive input stream, giving away ownership.
wxArchiveIterator	operator++ ()
	Position the input iterator at the next entry in the archive input stream.
wxArchiveIterator	operator++ (int)
	Position the input iterator at the next entry in the archive input stream.

Constructor & Destructor Documentation

wxArchiveIterator::wxArchiveIterator

(

)

Default constructor.

wxArchiveIterator::wxArchiveIterator

(

Arc &

arc

)

Construct the iterator that returns all the entries in the archive input stream arc.

Member Function Documentation

const T wxArchiveIterator::operator*

(

)

const

Returns an entry object from the archive input stream, giving away ownership.

wxArchiveIterator wxArchiveIterator::operator++

(

)

Position the input iterator at the next entry in the archive input stream.

wxArchiveIterator wxArchiveIterator::operator++

(

int

)

Position the input iterator at the next entry in the archive input stream.