Documented wxFFile and wxFFileStream and Co.

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

docs/latex/wx/category.tex

@@ -377,7 +377,8 @@ wxWindows has several small classes to work with disk files, see \helpref{file c
 overview}{wxfileoverview} for more details.
 
 \begin{twocollist}\itemsep=0pt
-\twocolitem{\helpref{wxFile}{wxfile}}{Low-level file input/output}
+\twocolitem{\helpref{wxFile}{wxfile}}{Low-level file input/output class.}
+\twocolitem{\helpref{wxFFile}{wxffile}}{Another low-level file input/output class.}
 \twocolitem{\helpref{wxTempFile}{wxtempfile}}{Class to safely replace an existing file}
 \twocolitem{\helpref{wxTextFile}{wxtextfile}}{Class for working with text files as with arrays of lines}
 \end{twocollist}
@@ -403,6 +404,8 @@ libraries, and to provide enhanced functionality.
 \twocolitem{\helpref{wxTextOutputStream}{wxtextoutputstream}}{Platform-independent text data output stream class}
 \twocolitem{\helpref{wxFileInputStream}{wxfileinputstream}}{File input stream class}
 \twocolitem{\helpref{wxFileOutputStream}{wxfileoutputstream}}{File output stream class}
+\twocolitem{\helpref{wxFFileInputStream}{wxffileinputstream}}{Another file input stream class}
+\twocolitem{\helpref{wxFFileOutputStream}{wxffileoutputstream}}{Another file output stream class}
 \twocolitem{\helpref{wxZlibInputStream}{wxzlibinputstream}}{Zlib (compression) input stream class}
 \twocolitem{\helpref{wxZlibOutputStream}{wxzliboutputstream}}{Zlib (compression) output stream class}
 \twocolitem{\helpref{wxSocketInputStream}{wxsocketinputstream}}{Socket input stream class}

docs/latex/wx/file.tex

@@ -148,7 +148,12 @@ Returns the file descriptor associated with the file.
 
 \constfunc{bool}{Eof}{\void}
 
-Returns TRUE if the end of the file has been reached.
+Returns TRUE if the end of the file has been reached (the last byte has been read).
+
+Note that the behaviour of the file pointer based class
+\helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof}
+will return TRUE here only if an attempt has been made to read
+{\it past} the last byte of the file.
 
 \membersection{wxFile::Exists}\label{wxfileexists}
 
@@ -208,7 +213,7 @@ The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was
 
 \membersection{wxFile::Seek}\label{wxfileseek}
 
-\func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxFile::SeekMode }{mode = wxFile::FromStart}}
+\func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 
 Seeks to the specified position.
 
@@ -216,7 +221,7 @@ Seeks to the specified position.
 
 \docparam{ofs}{Offset to seek to.}
 
-\docparam{mode}{One of {\bf wxFile::FromStart}, {\bf wxFile::FromEnd}, {\bf wxFile::FromCurrent}.}
+\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 
 \wxheading{Return value}
 
@@ -265,3 +270,197 @@ TRUE if the operation was successful.
 
 Writes the contents of the string to the file, returns TRUE on success.
 
+\section{\class{wxFFile}}\label{wxffile}
+
+A wxFFile performs raw file I/O. This is a very small class designed to
+minimize the overhead of using it - in fact, there is hardly any overhead at
+all, but using it brings you automatic error checking and hides differences
+between platforms and compilers.
+
+\wxheading{Derived from}
+
+None.
+
+\wxheading{Include files}
+
+<wx/ffile.h>
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt%
+\twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
+\twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
+\twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
+\end{twocollist}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFFile::wxFFile}\label{wxffileconstr}
+
+\func{}{wxFFile}{\void}
+
+Default constructor.
+
+\func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
+
+Opens a file with the given mode. As there is no way to return whether the
+operation was successful or not from the constructor you should test the
+return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
+fail.
+
+\func{}{wxFFile}{\param{FILE*}{ fp}}
+
+Opens a file with the given file pointer, which has already been opened.
+
+\wxheading{Parameters}
+
+\docparam{filename}{The filename.}
+
+\docparam{mode}{The mode in which to open the file using standard C strings.}
+
+\docparam{fp}{An existing file descriptor, such as stderr.}
+
+\membersection{wxFFile::\destruct{wxFFile}}
+
+\func{}{\destruct{wxFFile}}{\void}
+
+Destructor will close the file.
+
+NB: it is not virtual so you should {\it not} derive from wxFFile!
+
+\membersection{wxFFile::Attach}\label{wxffileattach}
+
+\func{void}{Attach}{\param{FILE*}{ fp}}
+
+Attaches an existing file pointer to the wxFFile object.
+
+The descriptor should be already opened and it will be closed by wxFFile
+object.
+
+\membersection{wxFFile::Close}\label{wxffileclose}
+
+\func{bool}{Close}{\void}
+
+Closes the file and returns TRUE on success.
+
+\membersection{wxFFile::Detach}\label{wxffiledetach}
+
+\func{void}{Detach}{\void}
+
+Get back a file pointer from wxFFile object - the caller is responsible for closing the file if this
+descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return FALSE after call to Detach().
+
+\membersection{wxFFile::fp}\label{wxffilefp}
+
+\constfunc{FILE *}{fp}{\void}
+
+Returns the file pointer associated with the file.
+
+\membersection{wxFFile::Eof}\label{wxffileeof}
+
+\constfunc{bool}{Eof}{\void}
+
+Returns TRUE if the an attempt has been made to read {\it past}
+the end of the file. 
+
+Note that the behaviour of the file descriptor based class
+\helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
+will return TRUE here as soon as the last byte of the file has been
+read.
+
+\membersection{wxFFile::Flush}\label{wxffileflush}
+
+\func{bool}{Flush}{\void}
+
+Flushes the file and returns TRUE on success.
+
+\membersection{wxFFile::IsOpened}\label{wxffileisopened}
+
+\constfunc{bool}{IsOpened}{\void}
+
+Returns TRUE if the file has been opened.
+
+\membersection{wxFFile::Length}\label{wxffilelength}
+
+\constfunc{size\_t}{Length}{\void}
+
+Returns the length of the file.
+
+\membersection{wxFFile::Open}\label{wxffileopen}
+
+\func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
+
+Opens the file, returning TRUE if successful.
+
+\wxheading{Parameters}
+
+\docparam{filename}{The filename.}
+
+\docparam{mode}{The mode in which to open the file.}
+
+\membersection{wxFFile::Read}\label{wxffileread}
+
+\func{size\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
+
+Reads the specified number of bytes into a buffer, returning the actual number read.
+
+\wxheading{Parameters}
+
+\docparam{buffer}{A buffer to receive the data.}
+
+\docparam{count}{The number of bytes to read.}
+
+\wxheading{Return value}
+
+The number of bytes read.
+
+\membersection{wxFFile::Seek}\label{wxffileseek}
+
+\func{bool}{Seek}{\param{long }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
+
+Seeks to the specified position and returs TRUE on success.
+
+\wxheading{Parameters}
+
+\docparam{ofs}{Offset to seek to.}
+
+\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
+
+\membersection{wxFFile::SeekEnd}\label{wxffileseekend}
+
+\func{bool}{SeekEnd}{\param{long }{ofs = 0}}
+
+Moves the file pointer to the specified number of bytes before the end of the file
+and returns TRUE on success.
+
+\wxheading{Parameters}
+
+\docparam{ofs}{Number of bytes before the end of the file.}
+
+\membersection{wxFFile::Tell}\label{wxffiletell}
+
+\constfunc{size\_t}{Tell}{\void}
+
+Returns the current position.
+
+\membersection{wxFFile::Write}\label{wxffilewrite}
+
+\func{size_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
+
+Writes the specified number of bytes from a buffer.
+
+\wxheading{Parameters}
+
+\docparam{buffer}{A buffer containing the data.}
+
+\docparam{count}{The number of bytes to write.}
+
+\wxheading{Return value}
+
+Number of bytes written.
+
+\membersection{wxFFile::Write}\label{wxffilewrites}
+
+\func{bool}{Write}{\param{const wxString\& }{s}}
+
+Writes the contents of the string to the file, returns TRUE on success.
+

docs/latex/wx/strmfile.tex

@@ -4,11 +4,17 @@
 \section{\class{wxFileInputStream}}\label{wxfileinputstream}
 
 This class represents data read in from a file. There are actually
-two such groups of classes: those documented here, and another group called
+two such groups of classes: this one is based on the \helpref{wxFile}{wxfile}
-wxFFileInputStream, wxFFileOutputStream and wxFFileStream which are not
+whereas \helpref{wxFFileInputStream}{wxffileinputstream} is based in
-based on file descriptors (and their wxWindows equivalent wxFile) but the
+the \helpref{wxFFile}{wxffile} class.
-FILE* type (and wxFFile). Apart from the different constructor ("FILE *file"
+
-instead if "int fd") their interface is identical.
+Note that \helpref{wxFile}{wxfile} and \helpref{wxFFile}{wxffile} differ
+in one aspect, namely when to report that the end of the file has been
+reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and 
+\helpref{wxFFile::Eof}{wxffileeof} and the behaviour of the stream
+classes reflects this difference, i.e. wxFileInputStream will report
+wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream
+will report wxSTREAM_EOF after trying to read {\it past} the last byte.
 
 \wxheading{Derived from}
 
@@ -20,7 +26,7 @@ instead if "int fd") their interface is identical.
 
 \wxheading{See also}
 
-\helpref{wxStreamBuffer}{wxstreamBuffer}, \helpref{wxFileOutputStream}{wxfileoutputstream}
+\helpref{wxBufferedInputStream}{wxbufferedinputstream}, \helpref{wxFileOutputStream}{wxfileoutputstream}, \helpref{wxFFileOutputStream}{wxffileoutputstream}
 
 % ----------
 % Members
@@ -59,11 +65,17 @@ Returns TRUE if the stream is initialized and ready.
 \section{\class{wxFileOutputStream}}\label{wxfileoutputstream}
 
 This class represents data written to a file. There are actually
-two such groups of classes: those documented here, and another group called
+two such groups of classes: this one is based on the \helpref{wxFile}{wxfile}
-wxFFileInputStream, wxFFileOutputStream and wxFFileStream which are not
+whereas \helpref{wxFFileInputStream}{wxffileinputstream} is based in
-based on file descriptors (and their wxWindows equivalent wxFile) but the
+the \helpref{wxFFile}{wxffile} class.
-FILE* type (and wxFFile). Apart from the different constructor ("FILE *file"
+
-instead if "int fd") their interface is identical.
+Note that \helpref{wxFile}{wxfile} and \helpref{wxFFile}{wxffile} differ
+in one aspect, namely when to report that the end of the file has been
+reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and 
+\helpref{wxFFile::Eof}{wxffileeof} and the behaviour of the stream
+classes reflects this difference, i.e. wxFileInputStream will report
+wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream
+will report wxSTREAM_EOF after trying to read {\it past} the last byte.
 
 \wxheading{Derived from}
 
@@ -75,7 +87,7 @@ instead if "int fd") their interface is identical.
 
 \wxheading{See also}
 
-\helpref{wxStreamBuffer}{wxstreamBuffer}, \helpref{wxFileInputStream}{wxfileinputstream}
+\helpref{wxBufferedOutputStream}{wxbufferedoutputstream}, \helpref{wxFileInputStream}{wxfileinputstream}, \helpref{wxFFileInputStream}{wxffileinputstream}
 
 % ----------
 % Members
@@ -135,3 +147,154 @@ Returns TRUE if the stream is initialized and ready.
 Initializes a new file stream in read-write mode using the specified 
 \it{iofilename} name.
 
+
+% -----------------------------------------------------------------------------
+% wxFFileInputStream
+% -----------------------------------------------------------------------------
+\section{\class{wxFFileInputStream}}\label{wxffileinputstream}
+
+This class represents data read in from a file. There are actually
+two such groups of classes: this one is based on the \helpref{wxFFile}{wxffile}
+whereas \helpref{wxFileInputStream}{wxfileinputstream} is based in
+the \helpref{wxFile}{wxfile} class.
+
+Note that \helpref{wxFile}{wxfile} and \helpref{wxFFile}{wxffile} differ
+in one aspect, namely when to report that the end of the file has been
+reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and 
+\helpref{wxFFile::Eof}{wxffileeof} and the behaviour of the stream
+classes reflects this difference, i.e. wxFileInputStream will report
+wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream
+will report wxSTREAM_EOF after trying to read {\it past} the last byte.
+
+\wxheading{Derived from}
+
+\helpref{wxInputStream}{wxinputstream}
+
+\wxheading{Include files}
+
+<wx/wfstream.h>
+
+\wxheading{See also}
+
+\helpref{wxBufferedInputStream}{wxbufferedinputstream}, \helpref{wxFFileOutputStream}{wxffileoutputstream}, \helpref{wxFileOutputStream}{wxfileoutputstream}
+
+% ----------
+% Members
+% ----------
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFFileInputStream::wxFFileInputStream}
+
+\func{}{wxFFileInputStream}{\param{const wxString\&}{ ifileName}}
+
+Opens the specified file using its {\it ifilename} name in read-only mode.
+
+\func{}{wxFFileInputStream}{\param{wxFFile\&}{ file}}
+
+Initializes a file stream in read-only mode using the file I/O object {\it file}.
+
+\func{}{wxFFileInputStream}{\param{FILE *}{ fp}}
+
+Initializes a file stream in read-only mode using the specified file pointer {\it fp}.
+
+\membersection{wxFFileInputStream::\destruct{wxFFileInputStream}}
+
+\func{}{\destruct{wxFFileInputStream}}{\void}
+
+Destructor.
+
+\membersection{wxFFileInputStream::Ok}
+
+\constfunc{bool}{Ok}{\void}
+
+Returns TRUE if the stream is initialized and ready.
+
+% -----------------------------------------------------------------------------
+% wxFFileOutputStream
+% -----------------------------------------------------------------------------
+\section{\class{wxFFileOutputStream}}\label{wxffileoutputstream}
+
+This class represents data written to a file. There are actually
+two such groups of classes: this one is based on the \helpref{wxFFile}{wxffile}
+whereas \helpref{wxFileInputStream}{wxffileinputstream} is based in
+the \helpref{wxFile}{wxfile} class.
+
+Note that \helpref{wxFile}{wxfile} and \helpref{wxFFile}{wxffile} differ
+in one aspect, namely when to report that the end of the file has been
+reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and 
+\helpref{wxFFile::Eof}{wxffileeof} and the behaviour of the stream
+classes reflects this difference, i.e. wxFileInputStream will report
+wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream
+will report wxSTREAM_EOF after trying to read {\it past} the last byte.
+
+\wxheading{Derived from}
+
+\helpref{wxOutputStream}{wxoutputstream}
+
+\wxheading{Include files}
+
+<wx/wfstream.h>
+
+\wxheading{See also}
+
+\helpref{wxBufferedOutputStream}{wxbufferedoutputstream}, \helpref{wxFFileInputStream}{wxffileinputstream}, \helpref{wxFileInputStream}{wxfileinputstream}
+
+% ----------
+% Members
+% ----------
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFFileOutputStream::wxFFileOutputStream}
+
+\func{}{wxFFileOutputStream}{\param{const wxString\&}{ ofileName}}
+
+Creates a new file with \it{ofilename} name and initializes the stream in
+write-only mode. 
+
+\func{}{wxFFileOutputStream}{\param{wxFFile\&}{ file}}
+
+Initializes a file stream in write-only mode using the file I/O object {\it file}.
+
+\func{}{wxFFileOutputStream}{\param{FILE *}{ fp}}
+
+Initializes a file stream in write-only mode using the file descriptor {\it fp}.
+
+\membersection{wxFFileOutputStream::\destruct{wxFFileOutputStream}}
+
+\func{}{\destruct{wxFFileOutputStream}}{\void}
+
+Destructor.
+
+\membersection{wxFFileOutputStream::Ok}
+
+\constfunc{bool}{Ok}{\void}
+
+Returns TRUE if the stream is initialized and ready.
+
+% -----------------------------------------------------------------------------
+% wxFFileStream
+% -----------------------------------------------------------------------------
+\section{\class{wxFFileStream}}
+
+\wxheading{Derived from}
+
+\helpref{wxFFileOutputStream}{wxFFileOutputStream}, \helpref{wxFFileInputStream}{wxffileinputstream}
+
+\wxheading{Include files}
+
+<wx/wfstream.h>
+
+\wxheading{See also}
+
+\helpref{wxStreamBuffer}{wxstreamBuffer}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFFileStream::wxFFileStream}
+
+\func{}{wxFFileStream}{\param{const wxString\&}{ iofileName}}
+
+Initializes a new file stream in read-write mode using the specified 
+\it{iofilename} name.
+
+

samples/typetest/typetest.cpp

@@ -347,7 +347,7 @@ void MyApp::DoStreamDemo3(wxCommandEvent& WXUNUSED(event))
     for (ch = 0; ch < 10; ch++)
         file_output.Write( &ch, 1 );
 
-    // Testing wxFileInoutStream
+    // Testing wxFileInputStream
     
     textCtrl.WriteText( "Reading 0 to 10 to wxFileInputStream:\n\n" );
 
@@ -396,7 +396,7 @@ void MyApp::DoStreamDemo3(wxCommandEvent& WXUNUSED(event))
     textCtrl.WriteText( "\n\n" );
 
     
-    // Testing wxFFileInoutStream
+    // Testing wxFFileInputStream
     
     textCtrl.WriteText( "Reading 0 to 10 to wxFFileInputStream:\n\n" );
 
@@ -442,6 +442,55 @@ void MyApp::DoStreamDemo3(wxCommandEvent& WXUNUSED(event))
 	case wxSTREAM_WRITE_ERROR:  textCtrl.WriteText( "wxSTREAM_WRITE_ERROR\n" ); break;
 	default: textCtrl.WriteText( "Huh?\n" ); break;
     }
+    textCtrl.WriteText( "\n\n" );
+
+    // Testing wxFFileInputStream
+    
+    textCtrl.WriteText( "Reading 0 to 10 to buffered wxFFileInputStream:\n\n" );
+
+    wxFFileInputStream ffile_input2( "test_wx.dat" );
+    wxBufferedInputStream buf_input( ffile_input2 );
+    for (ch2 = 0; ch2 < 11; ch2++)
+    {
+        buf_input.Read( &ch, 1 );
+	textCtrl.WriteText( "Value read: " );
+	textCtrl.WriteText( (char)(ch + '0') );
+	textCtrl.WriteText( ";  stream.LastError() returns: " );
+	switch (buf_input.LastError())
+	{
+	    case wxSTREAM_NOERROR:      textCtrl.WriteText( "wxSTREAM_NOERROR\n" ); break;
+	    case wxSTREAM_EOF:          textCtrl.WriteText( "wxSTREAM_EOF\n" ); break;
+	    case wxSTREAM_READ_ERROR:   textCtrl.WriteText( "wxSTREAM_READ_ERROR\n" ); break;
+	    case wxSTREAM_WRITE_ERROR:  textCtrl.WriteText( "wxSTREAM_WRITE_ERROR\n" ); break;
+	    default: textCtrl.WriteText( "Huh?\n" ); break;
+	}
+    }
+    textCtrl.WriteText( "\n" );
+    
+    textCtrl.WriteText( "Seeking to 0;  stream.LastError() returns: " );
+    buf_input.SeekI( 0 );
+    switch (buf_input.LastError())
+    {
+	case wxSTREAM_NOERROR:      textCtrl.WriteText( "wxSTREAM_NOERROR\n" ); break;
+	case wxSTREAM_EOF:          textCtrl.WriteText( "wxSTREAM_EOF\n" ); break;
+	case wxSTREAM_READ_ERROR:   textCtrl.WriteText( "wxSTREAM_READ_ERROR\n" ); break;
+	case wxSTREAM_WRITE_ERROR:  textCtrl.WriteText( "wxSTREAM_WRITE_ERROR\n" ); break;
+	default: textCtrl.WriteText( "Huh?\n" ); break;
+    }
+    textCtrl.WriteText( "\n" );
+    
+    buf_input.Read( &ch, 1 );
+    textCtrl.WriteText( "Value read: " );
+    textCtrl.WriteText( (char)(ch + '0') );
+    textCtrl.WriteText( ";  stream.LastError() returns: " );
+    switch (buf_input.LastError())
+    {
+	case wxSTREAM_NOERROR:      textCtrl.WriteText( "wxSTREAM_NOERROR\n" ); break;
+	case wxSTREAM_EOF:          textCtrl.WriteText( "wxSTREAM_EOF\n" ); break;
+	case wxSTREAM_READ_ERROR:   textCtrl.WriteText( "wxSTREAM_READ_ERROR\n" ); break;
+	case wxSTREAM_WRITE_ERROR:  textCtrl.WriteText( "wxSTREAM_WRITE_ERROR\n" ); break;
+	default: textCtrl.WriteText( "Huh?\n" ); break;
+    }
 
 }