X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/954b8ae60391d18b87a604e7919c87c0c6ae208b..e31f4da5f0e888e3bae947061be02a427c570372:/docs/latex/wx/inputstr.tex diff --git a/docs/latex/wx/inputstr.tex b/docs/latex/wx/inputstr.tex index ae346a3178..62b7a750ff 100644 --- a/docs/latex/wx/inputstr.tex +++ b/docs/latex/wx/inputstr.tex @@ -3,6 +3,8 @@ % ----------------------------------------------------------------------------- \section{\class{wxInputStream}}\label{wxinputstream} +wxInputStream is an abstract base class which may not be used directly. + \wxheading{Derived from} \helpref{wxStreamBase}{wxstreambase} @@ -11,50 +13,79 @@ -\wxheading{See also} - -\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} -\func{char}{Peek}{\void} +\constfunc{bool}{CanRead}{\void} -Returns the first character in the input queue without removing it. +Returns true if some data is available in the stream right now, so that +calling \helpref{Read()}{wxinputstreamread} wouldn't block. -\membersection{wxInputStream::GetC} +\membersection{wxInputStream::GetC}\label{wxinputstreamgetc} \func{char}{GetC}{\void} -Returns the first character in the input queue and removes it. +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} -\membersection{wxInputStream::Read} +\func{char}{Peek}{\void} + +Returns the first character in the input queue without removing it. -\func{wxInputStream\&}{Read}{\param{void *}{buffer}, \param{size_t}{ size}} +\wxheading{Note} -Reads the specified amount of bytes and stores the data in \it{buffer}. +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} + +\func{wxInputStream\&}{Read}{\param{void *}{buffer}, \param{size\_t}{ size}} + +Reads the specified amount of bytes and stores the data in {\it buffer}. \wxheading{Warning} @@ -65,7 +96,7 @@ The buffer absolutely needs to have at least the specified size. 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. @@ -75,33 +106,49 @@ The data is read until an error is raised by one of the two streams. This function returns a reference on the current object, so the user can test any states of the stream right away. -% ------------------ -% Position functions -% ------------------ -\membersection{wxInputStream::SeekI} +\membersection{wxInputStream::SeekI}\label{wxinputstreamseeki} -\func{off_t}{SeekI}{\param{off_t}{ pos}, \param{wxSeekMode}{ mode = wxFromStart}} +\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.} -\constfunc{off_t}{TellI}{\void} +\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.} + +\wxheading{Return value} + +The new stream position or wxInvalidOffset on error. + +\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.