docs/latex/wx/ffile.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        ffile.tex
   3 %% Purpose:     wxFFile documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     14.01.02 (extracted from file.tex)
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxFFile}}\label{wxffile}
  13
  14 wxFFile implements buffered file I/O. This is a very small class designed to
  15 minimize the overhead of using it - in fact, there is hardly any overhead at
  16 all, but using it brings you automatic error checking and hides differences
  17 between platforms and compilers. It wraps inside it a {\tt FILE *} handle used
  18 by standard C IO library (also known as {\tt stdio}).
  19
  20 \wxheading{Derived from}
  21
  22 None.
  23
  24 \wxheading{Include files}
  25
  26 <wx/ffile.h>
  27
  28 \twocolwidtha{7cm}
  29 \begin{twocollist}\itemsep=0pt%
  30 \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
  31 \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
  32 \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
  33 \end{twocollist}
  34
  35 \latexignore{\rtfignore{\wxheading{Members}}}
  36
  37 \membersection{wxFFile::wxFFile}\label{wxffileconstr}
  38
  39 \func{}{wxFFile}{\void}
  40
  41 Default constructor.
  42
  43 \func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
  44
  45 Opens a file with the given mode. As there is no way to return whether the
  46 operation was successful or not from the constructor you should test the
  47 return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
  48 fail.
  49
  50 \func{}{wxFFile}{\param{FILE*}{ fp}}
  51
  52 Opens a file with the given file pointer, which has already been opened.
  53
  54 \wxheading{Parameters}
  55
  56 \docparam{filename}{The filename.}
  57
  58 \docparam{mode}{The mode in which to open the file using standard C strings.
  59 Note that you should use {\tt "b"} flag if you use binary files under Windows
  60 or the results might be unexpected due to automatic newline conversion done
  61 for the text files.}
  62
  63 \docparam{fp}{An existing file descriptor, such as stderr.}
  64
  65 \membersection{wxFFile::\destruct{wxFFile}}
  66
  67 \func{}{\destruct{wxFFile}}{\void}
  68
  69 Destructor will close the file.
  70
  71 NB: it is not virtual so you should {\it not} derive from wxFFile!
  72
  73 \membersection{wxFFile::Attach}\label{wxffileattach}
  74
  75 \func{void}{Attach}{\param{FILE*}{ fp}}
  76
  77 Attaches an existing file pointer to the wxFFile object.
  78
  79 The descriptor should be already opened and it will be closed by wxFFile
  80 object.
  81
  82 \membersection{wxFFile::Close}\label{wxffileclose}
  83
  84 \func{bool}{Close}{\void}
  85
  86 Closes the file and returns true on success.
  87
  88 \membersection{wxFFile::Detach}\label{wxffiledetach}
  89
  90 \func{void}{Detach}{\void}
  91
  92 Get back a file pointer from wxFFile object - the caller is responsible for closing the file if this
  93 descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return false after call to Detach().
  94
  95 \membersection{wxFFile::fp}\label{wxffilefp}
  96
  97 \constfunc{FILE *}{fp}{\void}
  98
  99 Returns the file pointer associated with the file.
 100
 101 \membersection{wxFFile::Eof}\label{wxffileeof}
 102
 103 \constfunc{bool}{Eof}{\void}
 104
 105 Returns true if the an attempt has been made to read {\it past}
 106 the end of the file.
 107
 108 Note that the behaviour of the file descriptor based class
 109 \helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
 110 will return true here as soon as the last byte of the file has been
 111 read.
 112
 113 \membersection{wxFFile::Flush}\label{wxffileflush}
 114
 115 \func{bool}{Flush}{\void}
 116
 117 Flushes the file and returns true on success.
 118
 119 \membersection{wxFFile::IsOpened}\label{wxffileisopened}
 120
 121 \constfunc{bool}{IsOpened}{\void}
 122
 123 Returns true if the file has been opened.
 124
 125 \membersection{wxFFile::Length}\label{wxffilelength}
 126
 127 \constfunc{size\_t}{Length}{\void}
 128
 129 Returns the length of the file.
 130
 131 \membersection{wxFFile::Open}\label{wxffileopen}
 132
 133 \func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
 134
 135 Opens the file, returning true if successful.
 136
 137 \wxheading{Parameters}
 138
 139 \docparam{filename}{The filename.}
 140
 141 \docparam{mode}{The mode in which to open the file.}
 142
 143 \membersection{wxFFile::Read}\label{wxffileread}
 144
 145 \func{size\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 146
 147 Reads the specified number of bytes into a buffer, returning the actual number read.
 148
 149 \wxheading{Parameters}
 150
 151 \docparam{buffer}{A buffer to receive the data.}
 152
 153 \docparam{count}{The number of bytes to read.}
 154
 155 \wxheading{Return value}
 156
 157 The number of bytes read.
 158
 159 \membersection{wxFFile::Seek}\label{wxffileseek}
 160
 161 \func{bool}{Seek}{\param{long }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 162
 163 Seeks to the specified position and returns true on success.
 164
 165 \wxheading{Parameters}
 166
 167 \docparam{ofs}{Offset to seek to.}
 168
 169 \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 170
 171 \membersection{wxFFile::SeekEnd}\label{wxffileseekend}
 172
 173 \func{bool}{SeekEnd}{\param{long }{ofs = 0}}
 174
 175 Moves the file pointer to the specified number of bytes before the end of the file
 176 and returns true on success.
 177
 178 \wxheading{Parameters}
 179
 180 \docparam{ofs}{Number of bytes before the end of the file.}
 181
 182 \membersection{wxFFile::Tell}\label{wxffiletell}
 183
 184 \constfunc{size\_t}{Tell}{\void}
 185
 186 Returns the current position.
 187
 188 \membersection{wxFFile::Write}\label{wxffilewrite}
 189
 190 \func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
 191
 192 Writes the specified number of bytes from a buffer.
 193
 194 \wxheading{Parameters}
 195
 196 \docparam{buffer}{A buffer containing the data.}
 197
 198 \docparam{count}{The number of bytes to write.}
 199
 200 \wxheading{Return value}
 201
 202 Number of bytes written.
 203
 204 \membersection{wxFFile::Write}\label{wxffilewrites}
 205
 206 \func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv\&}{ conv = wxConvUTF8}}
 207
 208 Writes the contents of the string to the file, returns true on success.
 209
 210 The second argument is only meaningful in Unicode build of wxWindows when
 211 {\it conv} is used to convert {\it s} to multibyte representation.
 212
 213