From a84e46f23169fc203099c23643219d1a8b562b50 Mon Sep 17 00:00:00 2001
From: =?utf8?q?V=C3=A1clav=20Slav=C3=ADk?= <vslavik@fastmail.fm>
Date: Sun, 11 Apr 2004 20:58:56 +0000
Subject: [PATCH] stream classes docs and code fixes (part of patch 924438)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@26714 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/ffilestr.tex |  6 ++++++
 docs/latex/wx/fileistr.tex |  3 +++
 docs/latex/wx/fileostr.tex |  3 +++
 docs/latex/wx/inputstr.tex | 28 +++++++++++++++++++++++++++-
 docs/latex/wx/outptstr.tex | 12 +++++++++++-
 src/common/wfstream.cpp    |  4 ++--
 6 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/docs/latex/wx/ffilestr.tex b/docs/latex/wx/ffilestr.tex
index d686281db8..c413c1b332 100644
--- a/docs/latex/wx/ffilestr.tex
+++ b/docs/latex/wx/ffilestr.tex
@@ -15,6 +15,9 @@ reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and
 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.
+Related to EOF behavior, note that \helpref{SeekI()}{wxinputstreamseeki} 
+can seek beyond the end of the stream (file) and will thus not return 
+{\it wxInvalidOffset} for that.
 
 \wxheading{Derived from}
 
@@ -76,6 +79,9 @@ reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and
 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.
+Related to EOF behavior, note that \helpref{SeekO()}{wxoutputstreamseeko} 
+can seek beyond the end of the stream (file) and will thus not return 
+{\it wxInvalidOffset} for that.
 
 \wxheading{Derived from}
 
diff --git a/docs/latex/wx/fileistr.tex b/docs/latex/wx/fileistr.tex
index 865320a1a6..5c629ea09a 100644
--- a/docs/latex/wx/fileistr.tex
+++ b/docs/latex/wx/fileistr.tex
@@ -12,6 +12,9 @@ reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and
 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.
+Related to EOF behavior, note that \helpref{SeekI()}{wxinputstreamseeki} 
+can seek beyond the end of the stream (file) and will thus not return 
+{\it wxInvalidOffset} for that.
 
 \wxheading{Derived from}
 
diff --git a/docs/latex/wx/fileostr.tex b/docs/latex/wx/fileostr.tex
index c22c8b6114..294a83d1a1 100644
--- a/docs/latex/wx/fileostr.tex
+++ b/docs/latex/wx/fileostr.tex
@@ -15,6 +15,9 @@ reached. This is documented in \helpref{wxFile::Eof}{wxfileeof} and
 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.
+Related to EOF behavior, note that \helpref{SeekO()}{wxoutputstreamseeko} 
+can seek beyond the end of the stream (file) and will thus not return 
+{\it wxInvalidOffset} for that.
 
 \wxheading{Derived from}
 
diff --git a/docs/latex/wx/inputstr.tex b/docs/latex/wx/inputstr.tex
index daf42acc31..05f45a1884 100644
--- a/docs/latex/wx/inputstr.tex
+++ b/docs/latex/wx/inputstr.tex
@@ -34,7 +34,12 @@ Destructor.
 
 \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}
 
@@ -42,6 +47,11 @@ Returns the first character in the input queue and removes it.
 
 Returns true if the end of stream has been reached.
 
+\wxheading{Note}
+
+This cannot be really implemented for all streams and CanRead() is more 
+reliable than Eof().
+
 \membersection{wxInputStream::LastRead}\label{wxinputstreamlastread}
 
 \constfunc{size\_t}{LastRead}{\void}
@@ -54,6 +64,12 @@ Returns the last number of bytes read.
 
 Returns the first character in the input queue without removing it.
 
+\wxheading{Note}
+
+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}
 
 \func{wxInputStream\&}{Read}{\param{void *}{buffer}, \param{size\_t}{ size}}
@@ -85,6 +101,16 @@ any states of the stream right away.
 
 Changes the stream current position.
 
+\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.
+
 \membersection{wxInputStream::TellI}
 
 \constfunc{off\_t}{TellI}{\void}
diff --git a/docs/latex/wx/outptstr.tex b/docs/latex/wx/outptstr.tex
index b01a4b9a0f..5ebf899fa5 100644
--- a/docs/latex/wx/outptstr.tex
+++ b/docs/latex/wx/outptstr.tex
@@ -45,10 +45,20 @@ stream position.
 
 \membersection{wxOutputStream::SeekO}\label{wxoutputstreamseeko}
 
-\func{off\_t}{SeekO}{\param{off\_t}{ pos}, \param{wxSeekMode}{ mode}}
+\func{off\_t}{SeekO}{\param{off\_t}{ pos}, \param{wxSeekMode}{ mode = wxFromStart}}
 
 Changes the stream current position.
 
+\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.
+
 \membersection{wxOutputStream::TellO}
 
 \constfunc{off\_t}{TellO}{\void}
diff --git a/src/common/wfstream.cpp b/src/common/wfstream.cpp
index 0860226266..a6b287af0c 100644
--- a/src/common/wfstream.cpp
+++ b/src/common/wfstream.cpp
@@ -251,7 +251,7 @@ size_t wxFFileInputStream::OnSysRead(void *buffer, size_t size)
 
 off_t wxFFileInputStream::OnSysSeek(off_t pos, wxSeekMode mode)
 {
-    return ( m_file->Seek(pos, mode) ? pos : wxInvalidOffset );
+    return ( m_file->Seek(pos, mode) ? m_file->Tell() : wxInvalidOffset );
 }
 
 off_t wxFFileInputStream::OnSysTell() const
@@ -324,7 +324,7 @@ off_t wxFFileOutputStream::OnSysTell() const
 
 off_t wxFFileOutputStream::OnSysSeek(off_t pos, wxSeekMode mode)
 {
-    return ( m_file->Seek(pos, mode) ? pos : wxInvalidOffset );
+    return ( m_file->Seek(pos, mode) ? m_file->Tell() : wxInvalidOffset );
 }
 
 void wxFFileOutputStream::Sync()
-- 
2.45.2

