Documented wxFFile and wxFFileStream and Co.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4871 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Robert Roebling 1999-12-08 11:35:20 +00:00
parent 5ac8158ad9
commit 842d6c94bd
4 changed files with 432 additions and 18 deletions

View File

@ -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}

View File

@ -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.

View File

@ -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
wxFFileInputStream, wxFFileOutputStream and wxFFileStream which are not
based on file descriptors (and their wxWindows equivalent wxFile) but the
FILE* type (and wxFFile). Apart from the different constructor ("FILE *file"
instead if "int fd") their interface is identical.
two such groups of classes: this one is based on the \helpref{wxFile}{wxfile}
whereas \helpref{wxFFileInputStream}{wxffileinputstream} is based in
the \helpref{wxFFile}{wxffile} 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}
@ -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
wxFFileInputStream, wxFFileOutputStream and wxFFileStream which are not
based on file descriptors (and their wxWindows equivalent wxFile) but the
FILE* type (and wxFFile). Apart from the different constructor ("FILE *file"
instead if "int fd") their interface is identical.
two such groups of classes: this one is based on the \helpref{wxFile}{wxfile}
whereas \helpref{wxFFileInputStream}{wxffileinputstream} is based in
the \helpref{wxFFile}{wxffile} 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}
@ -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.

View File

@ -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;
}
}