RWFile Class Reference

Represents an abstraction of a filesystem regular file. More...

#include <rw/rwfile.h>

Inheritance diagram for RWFile:

Public Member Functions
	RWFile (const char *filename, const char *mode=0, bool large_file=false)
	~RWFile ()
const char *	Access () const
void	ClearErr ()
RWoffset	CurOffset () const
RWoffset64	CurOffset64 () const
bool	Eof () const
bool	eof () const
bool	Erase ()
bool	Error () const
bool	Exists () const
bool	Flush ()
const char *	GetName () const
FILE *	GetStream () const
bool	good () const
bool	IsEmpty () const
bool	isValid () const
bool	Read (bool &i)
bool	Read (char &c)
bool	Read (short &i)
bool	Read (int &i)
bool	Read (long &i)
bool	Read (unsigned char &c)
bool	Read (wchar_t &w)
bool	Read (unsigned short &i)
bool	Read (unsigned int &i)
bool	Read (unsigned long &i)
bool	Read (float &f)
bool	Read (double &s)
bool	Read (long long &i)
bool	Read (unsigned long long &i)
bool	Read (long double &d)
bool	Read (char *i, size_t n, int delim, size_t *count=0)
bool	Read (bool *i, size_t n, size_t *count=0)
bool	Read (char *i, size_t n, size_t *count=0)
bool	Read (short *i, size_t n, size_t *count=0)
bool	Read (int *i, size_t n, size_t *count=0)
bool	Read (long *i, size_t n, size_t *count=0)
bool	Read (wchar_t *i, size_t n, size_t *count=0)
bool	Read (unsigned char *c, size_t n, size_t *count=0)
bool	Read (unsigned short *i, size_t n, size_t *count=0)
bool	Read (unsigned int *i, size_t n, size_t *count=0)
bool	Read (unsigned long *i, size_t n, size_t *count=0)
bool	Read (float *i, size_t n, size_t *count=0)
bool	Read (double *i, size_t n, size_t *count=0)
bool	Read (long long *i, size_t n, size_t *count=0)
bool	Read (unsigned long long *i, size_t n, size_t *count=0)
bool	Read (long double *i, size_t n, size_t *count=0)
bool	Read (char *string)
bool	SeekTo (RWoffset offset)
bool	SeekTo64 (RWoffset64 offset)
bool	SeekToBegin ()
bool	SeekToEnd ()
bool	Write (bool i)
bool	Write (char i)
bool	Write (short i)
bool	Write (int i)
bool	Write (long i)
bool	Write (wchar_t i)
bool	Write (unsigned char i)
bool	Write (unsigned short i)
bool	Write (unsigned int i)
bool	Write (unsigned long i)
bool	Write (float f)
bool	Write (double d)
bool	Write (long long i)
bool	Write (unsigned long long i)
bool	Write (long double d)
bool	Write (const char *string)
bool	Write (const bool *i, size_t count)
bool	Write (const short *i, size_t count)
bool	Write (const int *i, size_t count)
bool	Write (const long *i, size_t count)
bool	Write (const wchar_t *i, size_t count)
bool	Write (const unsigned char *c, size_t N)
bool	Write (const unsigned short *i, size_t N)
bool	Write (const unsigned int *i, size_t N)
bool	Write (const unsigned long *i, size_t N)
bool	Write (const float *i, size_t count)
bool	Write (const double *i, size_t count)
bool	Write (const char *string, size_t)
bool	Write (const long long *i, size_t count)
bool	Write (const unsigned long long *i, size_t count)
bool	Write (const long double *i, size_t count)

Static Public Member Functions
static bool	Exists (const char *filename)
static bool	Exists (const char *filename, int mode)

Detailed Description

Class RWFile represents an abstraction of a filesystem regular file. The file is manipulated in binary mode by default. This class' interface is based on class PFile of the Interviews Class Library (1987, Stanford University). The member function names begin with upper case letters in order to maintain compatibility with class PFile.

If a function expects an RWFile to exist, your code should always check isValid() prior to calling that function. Failure to do so may cause a runtime error. For example:

RWFile aFile("filename");
//...
if(aFile.isValid() && ! aFile.Error()){
//...

Note that RWFile cannot anticipate or define the behavior of a program that calls any member function other than isValid() on an invalid RWFile object.

Synopsis

#include <rw/rwfile.h>
RWFile f("filename");

Persistence

None

Constructor & Destructor Documentation

RWFile::RWFile	(	const char *	filename,
		const char *	mode = 0,
		bool	large_file = false
	)

Constructs an RWFile to be used with the file name filename and with mode mode. The mode string conforms to POSIX fopen modes (see http://www.opengroup.org/onlinepubs/009695399/functions/fopen.html).

If mode is zero (the default), then the constructor attempts to open an existing file with the given filename for update (fopen mode "rb+"). If this is not possible, then it attempts to create a new file with the given filename (fopen mode "wb+"). The resulting object should be checked for validity using the function isValid().

The last parameter large_file is used to determine if the file should be opened in large file mode. On systems that are large file enabled, this parameter is ignored, and the file is always opened in large file mode. The default is false for compatibility with older versions of SourcePro, meaning that the file is not opened in large file mode. For newer versions and applications, we recommend that you pass a value of true for the large_file parameter, and that all file positioning calls be done with the large file safe functions SeekToBegin(), SeekToEnd(), SeekTo64(), and CurOffset64().

Note

Because this class is intended to encapsulate binary operations, it is important that it open or create files in binary mode. If a file mode is not specified, or is a NULL pointer, the file is opened in binary mode. Using binary mode is particularly important on systems where text mode file streams and binary streams are different.

RWFile::~RWFile

(

)

Performs any pending I/O operations and closes the file.

Member Function Documentation

const char* RWFile::Access

(

)

const

Returns the access mode with which the underlying FILE* was opened.

void RWFile::ClearErr

(

)

Resets error state so that neither Eof() nor Error() returns true.

RWoffset RWFile::CurOffset

(

)

const

Returns the current position, in bytes from the start of the file, as a 32-bit integer. Returns -1 on error or if the file position is beyond the representable range of RWoffset. May be used with both small and very large (more than 2GB) files.

RWoffset64 RWFile::CurOffset64

(

)

const

Returns the current offset, in bytes from the start of the file, as a 64-bit integer. May be used with both small and very large (more than 2GB) files.

bool RWFile::Eof

(

)

const

Returns true if an end-of-file has been reached.

bool RWFile::eof ( ) const

inline

Returns the results of the call to Eof().

bool RWFile::Erase

(

)

Erases the contents but does not close the file. Returns true if the operation was successful.

bool RWFile::Error

(

)

const

Returns true if a file I/O error has occurred. Before calling Error() you should call isValid() to determine if the file was opened/created successfully. Failure to do so could result in runtime errors.

bool RWFile::Exists ( ) const

inline

Returns true if the file exists.

static bool RWFile::Exists ( const char *  filename )

static

Returns true if a file with name filename exists.

static bool RWFile::Exists ( const char *  filename, int  mode  )

static

Returns true if a file with name filename exists and may be accessed according to the mode specified. The mode may be ORed together from one or more of:

Mode	Meaning
F_OK	Exists (Implied by any of the others)
X_OK	Executable or searchable
W_OK	Writable
R_OK	Readable

If your compiler or operating system does not support the POSIX access() function, then mode X_OK always returns false.

bool RWFile::Flush

(

)

Performs any pending I/O operations. Returns true if successful.

const char* RWFile::GetName ( ) const

inline

Returns the file name.

FILE* RWFile::GetStream

(

)

const

Returns a non-null FILE pointer for a valid file. Provided for users who need to perform implementation-dependent operations on FILE. Any changes in the state of the FILE object may render the behavior of the corresponding RWFile object undefined.

bool RWFile::good ( ) const

inline

Returns true if the file was successfully opened, there are no I/O errors, and the EOF has not been reached.

bool RWFile::IsEmpty

(

)

const

Returns true if the file contains no data, otherwise false, or on error.

bool RWFile::isValid

(

)

const

Returns true if the file was successfully opened, otherwise false.

bool RWFile::Read

(

bool &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

char &

c

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

short &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

int &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

long &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

unsigned char &

c

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

wchar_t &

w

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

unsigned short &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

unsigned int &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

unsigned long &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

float &

f

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

double &

s

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read

(

long long &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

Note

This function is available only if your compiler supports the long long type.

bool RWFile::Read

(

unsigned long long &

i

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

Note

This function is available only if your compiler supports the unsigned long long type.

bool RWFile::Read

(

long double &

d

)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

Note

This function is available only if your compiler supports the long double type.

bool RWFile::Read	(	char *	i,
		size_t	n,
		int	delim,
		size_t *	count = 0
	)

Extracts characters from the file, storing each in consecutive elements of the array i until either n characters have been extracted, or if (delim != EOF), the character specified by delim has been extracted.

If the delimiter is reached before n characters are extracted, the delimiter terminates the array i; if the delimiter is EOF and is reached before n characters are extracted, the method null terminates the array i.

The parameter n is the maximum number of characters to read, and must be less than or equal to the size of the array pointed to by i. The delim parameter specifies a delimiter to use as a termination point for extraction. The value of delim must be a valid character converted to int, or EOF.

The optional parameter count is a pointer to the actual number of characters read by the function.

This function returns true if n bytes were read from the file, or the specified delimiter was reached.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	bool *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	char *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

If the caller passes 0 for count, the program will compile without any warnings and call Read(char*, size_t, int, size_t*).

bool RWFile::Read	(	short *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	int *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	long *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	wchar_t *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read ( unsigned char *  c, size_t  n, size_t *  count = 0  )

inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read ( unsigned short *  i, size_t  n, size_t *  count = 0  )

inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read ( unsigned int *  i, size_t  n, size_t *  count = 0  )

inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read ( unsigned long *  i, size_t  n, size_t *  count = 0  )

inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	float *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	double *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

bool RWFile::Read	(	long long *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

This function is available only if your compiler supports the long long type.

bool RWFile::Read	(	unsigned long long *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

This function is available only if your compiler supports the unsigned long long type.

bool RWFile::Read	(	long double *	i,
		size_t	n,
		size_t *	count = 0
	)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note

The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.

This function is available only if your compiler supports the long double type.

bool RWFile::Read

(

char *

string

)

Deprecated:

As of SourcePro 11. Because of the risk of buffer overflow, we strongly recommend against using this function. Use Read(char*, size_t, size_t*) or Read(char*, size_t, int, size_t*) instead.

Reads a character string, including the terminating null character, into a block pointed to by string. Returns true if the read is successful.

Note

The caller is responsible for declaring string and for allocating the necessary storage before calling this function.

bool RWFile::SeekTo

(

RWoffset

offset

)

Repositions the file pointer to offset bytes from the start of the file. Can be used with both small and very large (more than 2GB) files. Returns true if the operation is successful. Returns -1 on error or if the requested seek offset is outside the range supported by the underlying file.

bool RWFile::SeekTo64

(

RWoffset64

offset

)

Repositions the file pointer to offset bytes from the start of the file. Can be used with both small and very large (more than 2GB) files. Returns true if the operation is successful. Returns -1 on error or if the requested seek offset is outside the range supported by the underlying file.

bool RWFile::SeekToBegin

(

)

Repositions the file pointer to the start of the file. Returns true if the operation is successful.

bool RWFile::SeekToEnd

(

)

Repositions the file pointer to the end of the file. Returns true if the operation is successful.

bool RWFile::Write

(

bool

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

char

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

short

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

int

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

long

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

wchar_t

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

unsigned char

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

unsigned short

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

unsigned int

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

unsigned long

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

float

f

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

double

d

)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write

(

long long

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

Note

This function is available only if your compiler supports the long long type.

bool RWFile::Write

(

unsigned long long

i

)

Writes the appropriate built-in type. Returns true if the write is successful.

Note

This function is available only if your compiler supports the unsigned long long type.

bool RWFile::Write

(

long double

d

)

Writes the appropriate built-in type. Returns true if the write is successful.

Note

This function is available only if your compiler supports the long double type.

bool RWFile::Write

(

const char *

string

)

Writes a character string, including the terminating null character, from a block pointed to by string. Returns true if the write is successful. Beware of non-terminated strings when using this function.

bool RWFile::Write	(	const bool *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const short *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const int *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const long *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const wchar_t *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned char *  c, size_t  N  )

inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned short *  i, size_t  N  )

inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned int *  i, size_t  N  )

inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned long *  i, size_t  N  )

inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const float *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const double *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const char *	string,
		size_t
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write	(	const long long *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

Note

This function is available only if your compiler supports the long long type.

bool RWFile::Write	(	const unsigned long long *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

Note

This function is available only if your compiler supports the unsigned long long type.

bool RWFile::Write	(	const long double *	i,
		size_t	count
	)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

Note

This function is available only if your compiler supports the long double type.