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 \wxheading{Library}
  29
  30 \helpref{wxBase}{librarieslist}
  31
  32 \twocolwidtha{7cm}
  33 \begin{twocollist}\itemsep=0pt%
  34 \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
  35 \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
  36 \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
  37 \end{twocollist}
  38
  39 \latexignore{\rtfignore{\wxheading{Members}}}
  40
  41
  42 \membersection{wxFFile::wxFFile}\label{wxffilector}
  43
  44 \func{}{wxFFile}{\void}
  45
  46 Default constructor.
  47
  48 \func{}{wxFFile}{\param{const wxString\&}{ filename}, \param{const wxString\&}{ mode = "r"}}
  49
  50 Opens a file with the given mode. As there is no way to return whether the
  51 operation was successful or not from the constructor you should test the
  52 return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
  53 fail.
  54
  55 \func{}{wxFFile}{\param{FILE*}{ fp}}
  56
  57 Opens a file with the given file pointer, which has already been opened.
  58
  59 \wxheading{Parameters}
  60
  61 \docparam{filename}{The filename.}
  62
  63 \docparam{mode}{The mode in which to open the file using standard C strings.
  64 Note that you should use {\tt "b"} flag if you use binary files under Windows
  65 or the results might be unexpected due to automatic newline conversion done
  66 for the text files.}
  67
  68 \docparam{fp}{An existing file descriptor, such as stderr.}
  69
  70
  71 \membersection{wxFFile::\destruct{wxFFile}}\label{wxffiledtor}
  72
  73 \func{}{\destruct{wxFFile}}{\void}
  74
  75 Destructor will close the file.
  76
  77 NB: it is not virtual so you should {\it not} derive from wxFFile!
  78
  79
  80 \membersection{wxFFile::Attach}\label{wxffileattach}
  81
  82 \func{void}{Attach}{\param{FILE*}{ fp}}
  83
  84 Attaches an existing file pointer to the wxFFile object.
  85
  86 The descriptor should be already opened and it will be closed by wxFFile
  87 object.
  88
  89
  90 \membersection{wxFFile::Close}\label{wxffileclose}
  91
  92 \func{bool}{Close}{\void}
  93
  94 Closes the file and returns \true on success.
  95
  96
  97 \membersection{wxFFile::Detach}\label{wxffiledetach}
  98
  99 \func{void}{Detach}{\void}
 100
 101 Get back a file pointer from wxFFile object -- the caller is responsible for closing the file if this
 102 descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return \false after call to Detach().
 103
 104
 105 \membersection{wxFFile::fp}\label{wxffilefp}
 106
 107 \constfunc{FILE *}{fp}{\void}
 108
 109 Returns the file pointer associated with the file.
 110
 111
 112 \membersection{wxFFile::Eof}\label{wxffileeof}
 113
 114 \constfunc{bool}{Eof}{\void}
 115
 116 Returns \true if the an attempt has been made to read {\it past}
 117 the end of the file.
 118
 119 Note that the behaviour of the file descriptor based class
 120 \helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
 121 will return \true here as soon as the last byte of the file has been
 122 read.
 123
 124 Also note that this method may only be called for opened files and may crash if
 125 the file is not opened.
 126
 127 \wxheading{See also}
 128
 129 \helpref{IsOpened}{wxffileisopened}
 130
 131
 132 \membersection{wxFFile::Error}\label{wxffileerror}
 133
 134 Returns \true if an error has occurred on this file, similar to the standard
 135 \texttt{ferror()} function.
 136
 137 Please note that this method may only be called for opened files and may crash
 138 if the file is not opened.
 139
 140 \wxheading{See also}
 141
 142 \helpref{IsOpened}{wxffileisopened}
 143
 144
 145 \membersection{wxFFile::Flush}\label{wxffileflush}
 146
 147 \func{bool}{Flush}{\void}
 148
 149 Flushes the file and returns \true on success.
 150
 151
 152 \membersection{wxFFile::GetKind}\label{wxffilegetfilekind}
 153
 154 \constfunc{wxFileKind}{GetKind}{\void}
 155
 156 Returns the type of the file. Possible return values are:
 157
 158 \begin{verbatim}
 159 enum wxFileKind
 160 {
 161   wxFILE_KIND_UNKNOWN,
 162   wxFILE_KIND_DISK,     // a file supporting seeking to arbitrary offsets
 163   wxFILE_KIND_TERMINAL, // a tty
 164   wxFILE_KIND_PIPE      // a pipe
 165 };
 166
 167 \end{verbatim}
 168
 169
 170 \membersection{wxFFile::IsOpened}\label{wxffileisopened}
 171
 172 \constfunc{bool}{IsOpened}{\void}
 173
 174 Returns \true if the file is opened. Most of the methods of this class may only
 175 be used for an opened file.
 176
 177
 178 \membersection{wxFFile::Length}\label{wxffilelength}
 179
 180 \constfunc{wxFileOffset}{Length}{\void}
 181
 182 Returns the length of the file.
 183
 184
 185 \membersection{wxFFile::Open}\label{wxffileopen}
 186
 187 \func{bool}{Open}{\param{const wxString\&}{ filename}, \param{const wxString\&}{ mode = "r"}}
 188
 189 Opens the file, returning \true if successful.
 190
 191 \wxheading{Parameters}
 192
 193 \docparam{filename}{The filename.}
 194
 195 \docparam{mode}{The mode in which to open the file.}
 196
 197
 198 \membersection{wxFFile::Read}\label{wxffileread}
 199
 200 \func{size\_t}{Read}{\param{void*}{ buffer}, \param{size\_t}{ count}}
 201
 202 Reads the specified number of bytes into a buffer, returning the actual number read.
 203
 204 \wxheading{Parameters}
 205
 206 \docparam{buffer}{A buffer to receive the data.}
 207
 208 \docparam{count}{The number of bytes to read.}
 209
 210 \wxheading{Return value}
 211
 212 The number of bytes read.
 213
 214
 215 \membersection{wxFFile::ReadAll}\label{wxffilereadall}
 216
 217 \func{bool}{ReadAll}{\param{wxString *}{ str}, \param{const wxMBConv\&}{ conv = wxConvAuto()}}
 218
 219 Reads the entire contents of the file into a string.
 220
 221 \wxheading{Parameters}
 222
 223 \docparam{str}{String to read data into.}
 224
 225 \docparam{conv}{Conversion object to use in Unicode build; by default supposes
 226 that file contents is encoded in UTF-8.}
 227
 228 \wxheading{Return value}
 229
 230 \true if file was read successfully, \false otherwise.
 231
 232
 233 \membersection{wxFFile::Seek}\label{wxffileseek}
 234
 235 \func{bool}{Seek}{\param{wxFileOffset }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 236
 237 Seeks to the specified position and returns \true on success.
 238
 239 \wxheading{Parameters}
 240
 241 \docparam{ofs}{Offset to seek to.}
 242
 243 \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 244
 245
 246 \membersection{wxFFile::SeekEnd}\label{wxffileseekend}
 247
 248 \func{bool}{SeekEnd}{\param{wxFileOffset }{ofs = 0}}
 249
 250 Moves the file pointer to the specified number of bytes before the end of the file
 251 and returns \true on success.
 252
 253 \wxheading{Parameters}
 254
 255 \docparam{ofs}{Number of bytes before the end of the file.}
 256
 257
 258 \membersection{wxFFile::Tell}\label{wxffiletell}
 259
 260 \constfunc{wxFileOffset}{Tell}{\void}
 261
 262 Returns the current position.
 263
 264
 265 \membersection{wxFFile::Write}\label{wxffilewrite}
 266
 267 \func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
 268
 269 Writes the specified number of bytes from a buffer.
 270
 271 \wxheading{Parameters}
 272
 273 \docparam{buffer}{A buffer containing the data.}
 274
 275 \docparam{count}{The number of bytes to write.}
 276
 277 \wxheading{Return value}
 278
 279 Number of bytes written.
 280
 281
 282 \membersection{wxFFile::Write}\label{wxffilewrites}
 283
 284 \func{bool}{Write}{\param{const wxString\& }{s}, \param{const wxMBConv\&}{ conv = wxConvAuto()}}
 285
 286 Writes the contents of the string to the file, returns \true on success.
 287
 288 The second argument is only meaningful in Unicode build of wxWidgets when
 289 {\it conv} is used to convert {\it s} to multibyte representation.
 290
 291