wxffile

wxffile implements buffered file i/o. this is a very small class designed to minimize the overhead of using it - in fact, there is hardly any overhead at all, but using it brings you automatic error checking and hides differences between platforms and compilers. it wraps inside it a file * handle used by standard c io library (also known as stdio).

derived from

none.

include files

<wx/ffile.h>

wxfromstart	count offset from the start of the file
wxfromcurrent	count offset from the current position of the file pointer
wxfromend	count offset from the end of the file (backwards)

members

wxffile::wxffile
wxffile::~wxffile
wxffile::attach
wxffile::close
wxffile::detach
wxffile::fp
wxffile::eof
wxffile::error
wxffile::flush
wxffile::getkind
wxffile::isopened
wxffile::length
wxffile::open
wxffile::read
wxffile::readall
wxffile::seek
wxffile::seekend
wxffile::tell
wxffile::write
wxffile::write

wxffile::wxffile

wxffile()

default constructor.

wxffile(const char* filename, const char* mode = "r")

opens a file with the given mode. as there is no way to return whether the operation was successful or not from the constructor you should test the return value of isopened to check that it didn't fail.

wxffile(file* fp)

opens a file with the given file pointer, which has already been opened.

parameters

filename

the filename.

mode

the mode in which to open the file using standard c strings. note that you should use "b" flag if you use binary files under windows or the results might be unexpected due to automatic newline conversion done for the text files.

fp

an existing file descriptor, such as stderr.

wxffile::~wxffile

~wxffile()

destructor will close the file.

nb: it is not virtual so you should not derive from wxffile!

wxffile::attach

void attach(file* fp)

attaches an existing file pointer to the wxffile object.

the descriptor should be already opened and it will be closed by wxffile object.

wxffile::close

bool close()

closes the file and returns true on success.

wxffile::detach

void detach()

get back a file pointer from wxffile object -- the caller is responsible for closing the file if this descriptor is opened. isopened() will return false after call to detach().

wxffile::fp

file * fp() const

returns the file pointer associated with the file.

wxffile::eof

bool eof() const

returns true if the an attempt has been made to read past the end of the file.

note that the behaviour of the file descriptor based class wxfile is different as wxfile::eof will return true here as soon as the last byte of the file has been read.

also note that this method may only be called for opened files and may crash if the file is not opened.

see also

isopened

wxffile::error

returns true if an error has occurred on this file, similar to the standard ferror() function.

please note that this method may only be called for opened files and may crash if the file is not opened.

see also

isopened

wxffile::flush

bool flush()

flushes the file and returns true on success.

wxffile::getkind

wxfilekind getkind() const

returns the type of the file. possible return values are:

enum wxfilekind
{
  wxfile_kind_unknown,
  wxfile_kind_disk,     // a file supporting seeking to arbitrary offsets
  wxfile_kind_terminal, // a tty
  wxfile_kind_pipe      // a pipe
};

wxffile::isopened

bool isopened() const

returns true if the file is opened. most of the methods of this class may only be used for an opened file.

wxffile::length

wxfileoffset length() const

returns the length of the file.

wxffile::open

bool open(const char* filename, const char* mode = "r")

opens the file, returning true if successful.

parameters

filename

the filename.

mode

the mode in which to open the file.

wxffile::read

size_t read(void* buffer, size_t count)

reads the specified number of bytes into a buffer, returning the actual number read.

parameters

buffer

a buffer to receive the data.

count

the number of bytes to read.

return value

the number of bytes read.

wxffile::readall

bool readall(wxstring * str, wxmbconv& conv = wxconvutf8)

reads the entire contents of the file into a string.

parameters

str

string to read data into.

conv

conversion object to use in unicode build; by default supposes that file contents is encoded in utf-8.

return value

true if file was read successfully, false otherwise.

wxffile::seek

bool seek(wxfileoffset ofs, wxseekmode mode = wxfromstart)

seeks to the specified position and returns true on success.

parameters

ofs

offset to seek to.

mode

one of wxfromstart, wxfromend, wxfromcurrent.

wxffile::seekend

bool seekend(wxfileoffset ofs = 0)

moves the file pointer to the specified number of bytes before the end of the file and returns true on success.

parameters

ofs

number of bytes before the end of the file.

wxffile::tell

wxfileoffset tell() const

returns the current position.

wxffile::write

size_t write(const void* buffer, size_t count)

writes the specified number of bytes from a buffer.

parameters

buffer

a buffer containing the data.

count

the number of bytes to write.

return value

number of bytes written.

wxffile::write

bool write(const wxstring& s, wxmbconv& conv = wxconvutf8)

writes the contents of the string to the file, returns true on success.

the second argument is only meaningful in unicode build of wxwidgets when conv is used to convert s to multibyte representation.