% -----------------------------------------------------------------------------
\section{\class{wxInputStream}}\label{wxinputstream}
+wxInputStream is an abstract base class which may not be used directly.
+
\wxheading{Derived from}
\helpref{wxStreamBase}{wxstreambase}
-\wxheading{See also}
+\wxheading{Include files}
+
+<wx/stream.h>
-\helpref{wxStreamBuffer}{wxstreambuffer}
+\latexignore{\rtfignore{\wxheading{Members}}}
% -----------
% ctor & dtor
% -----------
-\membersection{wxInputStream::wxInputStream}
+\membersection{wxInputStream::wxInputStream}\label{wxinputstreamctor}
\func{}{wxInputStream}{\void}
Creates a dummy input stream.
-\func{}{wxInputStream}{\param{wxStreamBuffer *}{sbuf}}
-
-Creates an input stream using the specified stream buffer \it{sbuf}. This
-stream buffer can point to another stream.
-
-\membersection{wxInputStream::\destruct{wxInputStream}}
+\membersection{wxInputStream::\destruct{wxInputStream}}\label{wxinputstreamdtor}
\func{}{\destruct{wxInputStream}}{\void}
Destructor.
-% -----------
-% IO function
-% -----------
-\membersection{wxInputStream::Peek}
+\membersection{wxInputStream::CanRead}\label{wxinputstreamcanread}
+
+\constfunc{bool}{CanRead}{\void}
+
+Returns true if some data is available in the stream right now, so that
+calling \helpref{Read()}{wxinputstreamread} wouldn't block.
+
+\membersection{wxInputStream::GetC}\label{wxinputstreamgetc}
+
+\func{char}{GetC}{\void}
+
+Returns the first character in the input queue and removes it,
+blocking until it appears if necessary.
+
+\wxheading{Note}
+
+If EOF, return value is undefined and LastRead() will return 0 and not 1.
+
+\membersection{wxInputStream::Eof}\label{wxinputstreameof}
+
+\constfunc{bool}{Eof}{\void}
+
+Returns true after an attempt has been made to read past the end of the
+stream.
+
+\wxheading{Note}
+
+In wxWidgets 2.6.x and below some streams returned Eof() when the last
+byte had been read rather than when an attempt had been made to read
+past the last byte. If you want to avoid depending on one behaviour or
+the other then call \helpref{LastRead()}{wxinputstreamlastread} to
+check the number of bytes actually read.
+
+\membersection{wxInputStream::LastRead}\label{wxinputstreamlastread}
+
+\constfunc{size\_t}{LastRead}{\void}
+
+Returns the last number of bytes read.
+
+\membersection{wxInputStream::Peek}\label{wxinputstreampeek}
\func{char}{Peek}{\void}
Returns the first character in the input queue without removing it.
-\membersection{wxInputStream::GetC}
+\wxheading{Note}
-\func{char}{GetC}{\void}
+Blocks until something appears in the stream if necessary, if nothing
+ever does (i.e. EOF) LastRead() will return 0 (and the return value is
+undefined), otherwise LastRead() returns 1.
+
+\membersection{wxInputStream::Read}\label{wxinputstreamread}
-Returns the first character in the input queue and removes it.
+\func{wxInputStream\&}{Read}{\param{void *}{buffer}, \param{size\_t}{ size}}
-\membersection{wxInputStream::Read}
+Reads the specified amount of bytes and stores the data in {\it buffer}.
-\func{wxInputStream\&}{Read}{\param{void *}{buffer}, \param{size_t}{ size}}
+\wxheading{Warning}
-Reads the specified amount of bytes and stores the data in \it{buffer}.
+The buffer absolutely needs to have at least the specified size.
-\it{WARNING!} The buffer absolutely needs to have at least the specified size.
+\wxheading{Return value}
This function returns a reference on the current object, so the user can test
any states of the stream right away.
-\func{wxInputStream\&}{Read}{\param{wxOutputStream\&}{ stream_out}}
+\func{wxInputStream\&}{Read}{\param{wxOutputStream\&}{ stream\_out}}
Reads data from the input queue and stores it in the specified output stream.
The data is read until an error is raised by one of the two streams.
-% ------------------
-% Position functions
-% ------------------
-\membersection{wxInputStream::SeekI}
+\wxheading{Return value}
+
+This function returns a reference on the current object, so the user can test
+any states of the stream right away.
-\func{off_t}{SeekI}{\param{off_t}{ pos}, \param{wxSeekMode}{ mode = wxFromStart}}
+\membersection{wxInputStream::SeekI}\label{wxinputstreamseeki}
+
+\func{off\_t}{SeekI}{\param{off\_t}{ pos}, \param{wxSeekMode}{ mode = wxFromStart}}
Changes the stream current position.
-\membersection{wxInputStream::TellI}
+\wxheading{Parameters}
+
+\docparam{pos}{Offset to seek to.}
+
+\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
+
+\wxheading{Return value}
+
+The new stream position or wxInvalidOffset on error.
-\constfunc{off_t}{TellI}{\void}
+\membersection{wxInputStream::TellI}\label{wxinputstreamtelli}
+
+\constfunc{off\_t}{TellI}{\void}
Returns the current stream position.
-% ---------------
-% State functions
-% ---------------
-\membersection{wxInputStream::InputStreamBuffer}
+\membersection{wxInputStream::Ungetch}\label{wxinputstreamungetch}
-\func{wxStreamBuffer*}{InputStreamBuffer}{\void}
+\func{size\_t}{Ungetch}{\param{const char*}{ buffer}, \param{size\_t}{ size}}
-Returns the stream buffer associated with the input stream.
+This function is only useful in {\it read} mode. It is the manager of the "Write-Back"
+buffer. This buffer acts like a temporary buffer where data which has to be
+read during the next read IO call are put. This is useful when you get a big
+block of data which you didn't want to read: you can replace them at the top
+of the input queue by this way.
-\membersection{wxInputStream::LastRead}
+Be very careful about this call in connection with calling SeekI() on the same
+stream. Any call to SeekI() will invalidate any previous call to this method
+(otherwise you could SeekI() to one position, "unread" a few bytes there, SeekI()
+to another position and data would be either lost or corrupted).
-\constfunc{size_t}{LastRead}{\void}
+\wxheading{Return value}
-Returns the last number of bytes read.
+Returns the amount of bytes saved in the Write-Back buffer.
+
+\func{bool}{Ungetch}{\param{char }{c}}
+
+This function acts like the previous one except that it takes only one
+character: it is sometimes shorter to use than the generic function.
projects / wxWidgets.git / blobdiff