wxFFile Class Reference

#include <wx/ffile.h>

Detailed Description

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).

Library:  wxBase

Category:  File Handling

See Also

wxFFile::IsOpened

Public Member Functions
	wxFFile ()
	wxFFile (FILE *fp)
	Opens a file with the given file pointer, which has already been opened.
	wxFFile (const wxString &filename, const wxString &mode="r")
	Opens a file with the given mode.
	~wxFFile ()
	Destructor will close the file.
void	Attach (FILE *fp, const wxString &name=wxEmptyString)
	Attaches an existing file pointer to the wxFFile object.
bool	Close ()
	Closes the file and returns true on success.
FILE *	Detach ()
	Get back a file pointer from wxFFile object – the caller is responsible for closing the file if this descriptor is opened.
bool	Eof () const
	Returns true if an attempt has been made to read past the end of the file.
bool	Error () const
	Returns true if an error has occurred on this file, similar to the standard ferror() function.
bool	Flush ()
	Flushes the file and returns true on success.
wxFileKind	GetKind () const
	Returns the type of the file.
const wxString &	GetName () const
	Returns the file name.
bool	IsOpened () const
	Returns true if the file is opened.
wxFileOffset	Length () const
	Returns the length of the file.
bool	Open (const wxString &filename, const wxString &mode="r")
	Opens the file, returning true if successful.
size_t	Read (void *buffer, size_t count)
	Reads the specified number of bytes into a buffer, returning the actual number read.
bool	ReadAll (wxString *str, const wxMBConv &conv=wxConvAuto())
	Reads the entire contents of the file into a string.
bool	Seek (wxFileOffset ofs, wxSeekMode mode=wxFromStart)
	Seeks to the specified position and returns true on success.
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.
wxFileOffset	Tell () const
	Returns the current position.
bool	Write (const wxString &str, const wxMBConv &conv=wxConvAuto())
	Writes the contents of the string to the file, returns true on success.
size_t	Write (const void *buffer, size_t count)
	Writes the specified number of bytes from a buffer.
FILE *	fp () const
	Returns the file pointer associated with the file.

Constructor & Destructor Documentation

wxFFile::wxFFile

(

)

wxFFile::wxFFile

(

FILE *

fp

)

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

Parameters

fp	An existing file descriptor, such as stderr.

wxFFile::wxFFile	(	const wxString &	filename,
		const wxString &	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.

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.

wxFFile::~wxFFile

(

)

Destructor will close the file.

Note

it is not virtual so you should not derive from wxFFile!

Member Function Documentation

void wxFFile::Attach	(	FILE *	fp,
		const wxString &	name = wxEmptyString
	)

Attaches an existing file pointer to the wxFFile object.

The descriptor should be already opened and it will be closed by wxFFile object.

bool wxFFile::Close

(

)

Closes the file and returns true on success.

FILE* wxFFile::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().

Returns

The FILE pointer (this is new since wxWidgets 3.0.0, in the previous versions this method didn't return anything).

bool wxFFile::Eof

(

)

const

Returns true if 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.

Todo:

THIS METHOD MAY CRASH? DOESN'T SOUND GOOD

See Also

IsOpened()

bool wxFFile::Error

(

)

const

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.

Todo:

THIS METHOD MAY CRASH? DOESN'T SOUND GOOD

See Also

IsOpened()

bool wxFFile::Flush

(

)

Flushes the file and returns true on success.

FILE* wxFFile::fp

(

)

const

Returns the file pointer associated with the file.

wxFileKind wxFFile::GetKind

(

)

const

Returns the type of the file.

See Also

wxFileKind

const wxString& wxFFile::GetName

(

)

const

Returns the file name.

This is the name that was specified when the object was constructed or to the last call to Open(). Notice that it may be empty if Attach() was called without specifying the name.

bool wxFFile::IsOpened

(

)

const

Returns true if the file is opened.

Most of the methods of this class may only be used for an opened file.

wxFileOffset wxFFile::Length

(

)

const

Returns the length of the file.

bool wxFFile::Open	(	const wxString &	filename,
		const wxString &	mode = "r"
	)

Opens the file, returning true if successful.

Parameters

filename	The filename.
mode	The mode in which to open the file.

size_t wxFFile::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.

Returns

The number of bytes read.

bool wxFFile::ReadAll	(	wxString *	str,
		const wxMBConv &	conv = wxConvAuto()
	)

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.

Returns

true if file was read successfully, false otherwise.

bool wxFFile::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.

bool wxFFile::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.

wxFileOffset wxFFile::Tell

(

)

const

Returns the current position.

bool wxFFile::Write	(	const wxString &	str,
		const wxMBConv &	conv = wxConvAuto()
	)

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 str to multibyte representation.

size_t wxFFile::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.

Returns

The number of bytes written.