Some improvements to the zip stream docs thanks to helpful feedback

from Andrew Ziem, Stas Sergeev and Artur Kornacki.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@33058 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/latex/wx/arc.tex b/docs/latex/wx/arc.tex
index f84fc46f6ba7b356cb102c496880f0bc3029f522..eee37b4d52fde03526ee958160450f6f5ca0a7ad 100644 (file)
--- a/docs/latex/wx/arc.tex
+++ b/docs/latex/wx/arc.tex
@@ -10,7 +10,8 @@
 \section{Archive formats such as zip}\label{wxarc}
 
 The archive classes handle archive formats such as zip, tar, rar and cab.
-Currently only the wxZip classes are included.
+Currently only the wxZip classes are included. wxTar classes are under
+development at \urlref{wxCode}{http://wxcode.sf.net}.
 
 For each archive type, there are the following classes (using zip here
 as an example):
@@ -65,31 +66,39 @@ For example:
 
 \helpref{Archive formats such as zip}{wxarc}
 
-\helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} returns an
-entry object containing the meta-data for the next entry in the archive
-(and gives away ownership). Reading from the input stream then returns
-the entry's data. Eof() becomes true after an attempt has been made to
-read past the end of the entry's data.
+\helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} returns a pointer
+to entry object containing the meta-data for the next entry in the archive
+(and gives away ownership). Reading from the input stream then returns the
+entry's data. Eof() becomes true after an attempt has been made to read past
+the end of the entry's data.
 
 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
 
 \begin{verbatim}
-    wxDEFINE_SCOPED_PTR_TYPE(wxZipEntry);
+    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
     wxZipEntryPtr entry;
 
     wxFFileInputStream in(_T("test.zip"));
     wxZipInputStream zip(in);
-    wxTextInputStream txt(zip);
-    wxString data;
 
     while (entry.reset(zip.GetNextEntry()), entry.get() != NULL)
     {
-        wxString name = entry->GetName();    // access meta-data
-        txt >> data;                         // access data
+        // access meta-data
+        wxString name = entry->GetName();
+        // read 'zip' to access the entry's data
     }
 
 \end{verbatim}
 
+The \helpref{smart pointer}{wxscopedptr} type {\em wxZipEntryPtr}
+can be created like this:
+
+\begin{verbatim}
+    #include <wx/ptr_scpd.h>
+    wxDEFINE_SCOPED_PTR_TYPE(wxZipEntry);
+
+\end{verbatim}
+
 
 \subsection{Modifying an archive}\label{wxarcmodify}
 
@@ -103,18 +112,22 @@ much more efficient than transferring the data using Read() and Write()
 since it will copy them without decompressing and recompressing them.
 
 In general modifications are not possible without rewriting the archive,
-though it may be possible in some limited cases. Even then, rewriting
-the archive is usually a better choice since a failure can be handled
-without losing the whole archive.
+though it may be possible in some limited cases. Even then, rewriting the
+archive is usually a better choice since a failure can be handled without
+losing the whole
+archive. \helpref{wxTempFileOutputStream}{wxtempfileoutputstream} can
+be helpful to do this.
 
 For example to delete all entries matching the pattern "*.txt":
 
 \begin{verbatim}
-    wxFFileInputStream in(_T("in.zip"));
-    wxFFileOutputStream out(_T("out.zip"));
+    wxFFileInputStreamPtr in(new wxFFileInputStream(_T("test.zip")));
+    wxTempFileOutputStream out(_T("test.zip"));
 
-    wxZipInputStream inzip(in);
+    wxZipInputStream inzip(*in);
     wxZipOutputStream outzip(out);
+
+    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
     wxZipEntryPtr entry;
 
     // transfer any meta-data for the archive as a whole (the zip comment
@@ -127,7 +140,22 @@ For example to delete all entries matching the pattern "*.txt":
             if (!outzip.CopyEntry(entry.release(), inzip))
                 break;
 
-    bool success = inzip.Eof() && outzip.Close();
+    // close the input stream by releasing the pointer to it, do this
+    // before closing the output stream so that the file can be replaced
+    in.reset();
+
+    // you can check for success as follows
+    bool success = inzip.Eof() && outzip.Close() && out.Commit();
+
+\end{verbatim}
+
+The \helpref{smart pointer}{wxscopedptr} types {\em wxZipEntryPtr}
+and {\em wxFFileInputStreamPtr} can be created like this:
+
+\begin{verbatim}
+    #include <wx/ptr_scpd.h>
+    wxDEFINE_SCOPED_PTR_TYPE(wxZipEntry);
+    wxDEFINE_SCOPED_PTR_TYPE(wxFFileInputStream);
 
 \end{verbatim}
 
@@ -159,7 +187,7 @@ it is better to convert the local name to the archive's internal format
 and search for that:
 
 \begin{verbatim}
-    wxDEFINE_SCOPED_PTR_TYPE(wxZipEntry);
+    // 'smart pointer' type created with wxDEFINE_SCOPED_PTR_TYPE
     wxZipEntryPtr entry;
 
     // convert the local name we are looking for into the internal format
@@ -251,7 +279,8 @@ So there is a class factory for each archive type, derived from
  \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}, which can create
 the other classes.
 
-For example, given {\it wxArchiveClassFactory* factory}:
+For example, given {\it wxArchiveClassFactory* factory}, streams and
+entries can be created like this:
 
 \begin{verbatim}
     // create streams without knowing their type
@@ -263,6 +292,18 @@ For example, given {\it wxArchiveClassFactory* factory}:
 
 \end{verbatim}
 
+The \helpref{smart pointer}{wxscopedptr} types {\em wxArchiveInputStreamPtr},
+{\em wxArchiveOutputStreamPtr} and {\em wxArchiveEntryPtr} would need to
+have already have been defined, which could be done like this:
+
+\begin{verbatim}
+    #include <wx/ptr_scpd.h>
+    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveInputStream);
+    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveOutputStream);
+    wxDEFINE_SCOPED_PTR_TYPE(wxArchiveEntry);
+
+\end{verbatim}
+
 The class factory itself can either be created explicitly:
 
 \begin{verbatim}

diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index 29d02c9d109748bae4f1c21c93845602594fea30..cc9d9eb9f19b16420c03ebdc787a9473dd4bdb57 100644 (file)
--- a/docs/latex/wx/category.tex
+++ b/docs/latex/wx/category.tex
@@ -502,6 +502,7 @@ libraries, and to provide enhanced functionality.
 \twocolitem{\helpref{wxZlibInputStream}{wxzlibinputstream}}{Zlib (compression) input stream class}
 \twocolitem{\helpref{wxZlibOutputStream}{wxzliboutputstream}}{Zlib (compression) output stream class}
 \twocolitem{\helpref{wxZipInputStream}{wxzipinputstream}}{Input stream for reading from ZIP archives}
+\twocolitem{\helpref{wxZipOutputStream}{wxzipoutputstream}}{Output stream for writing from ZIP archives}
 \twocolitem{\helpref{wxSocketInputStream}{wxsocketinputstream}}{Socket input stream class}
 \twocolitem{\helpref{wxSocketOutputStream}{wxsocketoutputstream}}{Socket output stream class}
 \end{twocollist}

diff --git a/docs/latex/wx/zipstrm.tex b/docs/latex/wx/zipstrm.tex
index c738495cbb3c96cfac20280074fed3c53dd56a42..998e75e47daf71e423027a7f456e61908687805d 100644 (file)
--- a/docs/latex/wx/zipstrm.tex
+++ b/docs/latex/wx/zipstrm.tex
@@ -433,6 +433,9 @@ the wxZipInputStream then returns the entry's data. Eof() becomes true
 after an attempt has been made to read past the end of the entry's data.
 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
 
+Note that in general zip entries are not seekable, and
+wxZipInputStream::SeekI() always returns wxInvalidOffset.
+
 \wxheading{Derived from}
 
 \helpref{wxArchiveInputStream}{wxarchiveinputstream}
@@ -467,6 +470,10 @@ no effect on the stream's data.
 
 Compatibility constructor.
 
+When this constructor is used, an emulation of seeking is
+switched on for compatibility with previous versions. Note however,
+that it is deprecated.
+
 
 \membersection{wxZipInputStream::CloseEntry}\label{wxzipinputstreamcloseentry}