RWFile

Module:  Essential Tools Module   Group:  File System Classes

Does not inherit

• Local Index
• Synopsis
• Description
• Persistence
• Public Constructors
• Public Destructor
• Public Member Functions
• Static Public Member Functions
• Related Global Operators

Members

Access() ClearErr() CurOffset() CurOffset64() eof() Eof()

Erase() Error() Exists() Flush() GetName() GetStream()

good() IsEmpty() isValid() Read() RWFile() SeekTo()

SeekTo64() SeekToBegin() SeekToEnd() Write() ~RWFile()

Non-Members

operator>>()

operator<<()

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

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.

None

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 will attempt to open an existing file with the given filename for update (fopen mode "rb+"). If this is not possible, then it will attempt to create a new file with the given filename (fopen mode "wb+"). The resulting object should be checked for validity using function isValid().

---

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 will be opened in binary mode. Using binary mode is particularly important on systems where text mode file streams and binary streams are different.

---

The last parameter large_file is a hint to the implementation that the large file API should be used. It may be ignored.

~RWFile();

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

const char*
Access() const;

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

void
ClearErr();

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

RWoffset
CurOffset() const;

Returns the current position, in bytes from the start of the file, as a 32-bit integer. Will return -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 2 gb) files.

RWoffset64
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 2 gb) files.

bool
eof() const;

Returns the results of the call to Eof().

bool
Eof() const;

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

bool
Erase();

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

bool
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
Exists() const;

Returns true if the file exists.

bool
Flush();

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

const char*
GetName() const;

Returns the file name.

FILE*
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
good() const;

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

bool
IsEmpty() const;

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

bool
isValid() const;

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

bool
Read(char& c);
bool
Read(wchar_t& wc);
bool
Read(short& i);
bool
Read(int& i);
bool
Read(long& i);
bool
Read(long long& i);

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

bool
Read(unsigned char& c);
bool
Read(unsigned short& i);
bool
Read(unsigned int& i);
bool
Read(unsigned long& i);
bool
Read(unsigned long long& i);

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

bool
Read(float& f);
bool
Read(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 will be interpreted as successfully reading a null string, and will return true.

bool
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 will be interpreted as successfully reading a null string, and will return true. Note: This operator function is available only if your compiler supports the long double type.

bool
Read(char* i, size_t count);

bool
Read(char* i, size_t count, int delim);

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

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

The parameter count 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.

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

bool
Read(wchar_t* i, size_t count);
bool
Read(short* i, size_t count);
bool
Read(int* i, size_t count);
bool
Read(long* i, size_t count);
bool
Read(long long* i, size_t count);

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

bool
Read(unsigned char* i, size_t count);
bool
Read(unsigned short* i,size_t count);
bool
Read(unsigned int* i, size_t count);
bool
Read(unsigned long* i, size_t count);
bool
Read(unsigned long long* i, size_t count);

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

bool
Read(float* i, size_t count);
bool
Read(double* i, size_t count);

Reads count instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful. Note that you are responsible for declaring i and for allocating the necessary storage before calling this function.

Read(long double* i, size_t count);

Reads count instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful. Note that you are responsible for declaring i and for allocating the necessary storage before calling this function. Note: This operator function is available only if your compiler supports the long double type.

bool
Read(char* string);

WARNING: This method is deprecated and is no longer supported. Be aware that it may be removed in a future release. Because of the risk of buffer overflow, we strongly recommend against using this function. Use Read(char* i, size_t count) 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 that you are responsible for declaring string and for allocating the necessary storage before calling this function. Beware of overflow when using this function.

bool
SeekTo(RWoffset offset);
bool
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 2 gb) files. Returns true if the operation is successful; will return -1 on error or if the requested seek offset is outside the range supported by the underlying file.

bool
SeekToBegin();

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

bool
SeekToEnd();

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

bool
Write(char i);
bool
Write(wchar_t i);
bool
Write(short i);
bool
Write(int i);
bool
Write(long i);
bool
Write(long long i);

Note: This operator function is available only if your compiler supports the long long i type.

bool
Write(unsigned char i);
bool
Write(unsigned short i);
bool
Write(unsigned int i);
bool
Write(unsigned long i);
bool
Write(unsigned long long i);

Note: This operator function is available only if your compiler supports the unsigned long long i type.

bool
Write(float f);
bool
Write(double d);

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

bool
Write(long double d);

Writes the appropriate built-in type. Returns true if the write is successful. Note: This operator function is available only if your compiler supports the long double d type.

bool
Write(const char* i, size_t count);
bool
Write(const wchar_t* 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 long long* i, size_t count);

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

bool
Write(const unsigned char* i, size_t count);
bool
Write(const unsigned short* i,size_t count);
bool
Write(const unsigned int* i, size_t count);
bool
Write(const unsigned long* i, size_t count);
bool
Write(const unsigned long long* i, size_t count);

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

bool
Write(const float* i, size_t count);
bool
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.

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 operator function is available only if your compiler supports the long double type.

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

static bool
Exists(const char* filename, int mode = F_OK);

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:

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 will always return false.

RWFile&
operator<<(RWFile&, const RWCString& str);

Saves string str to RWFile.

RWFile&
operator<<(RWFile&, const RWDate& date);

WARNING: This method is deprecated and is no longer supported. Be aware that it may be removed in a future release.

Saves the date date to RWFile.

RWFile&
operator<<(RWFile&, const RWInteger& x);

Saves the RWInteger x to RWFile.

RWFile&
operator<<(RWFile&, const RWTime& t);

WARNING: This method is deprecated and is no longer support. Be aware that it may be removed in a future release.

Saves RWTime t to RWFile.

RWFile&
operator>>(RWFile&, RWTime& t);

WARNING: This method is deprecated and is no longer support. Be aware that it may be removed in a future release.

Restores an RWTime into t from a virtual stream or RWFile, respectively, replacing the previous contents of t.

RWFile&
operator>>(RWFile&, RWCString& str);

Restores a string into str from a virtual stream or RWFile, respectively, replacing the previous contents of str.

RWFile&
operator>>(RWFile&, RWDate& date);

WARNING: This method is deprecated and is no longer support. Be aware that it may be removed in a future release.

Restores the date into date from a virtual stream or RWFile, respectively, replacing the previous contents of date.

RWFile&
operator>>(RWFile&, RWInteger& x);

Restores an RWInteger into x from a virtual stream or RWFile, respectively, replacing the previous contents of x.

RWFile&
operator<<(RWFile& strm, const RWTPtrDeque<T,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrDlist<T,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrHashMap<K,T,H,EQ,A>&
           coll);
RWFile&
operator<<(RWFile& strm, 
           const RWTPtrHashMultiMap<K,T,H,EQ,A>& coll);
operator<<(RWFile& strm, 
           const RWTPtrHashMultiSet<T,H,EQ,A>& coll); 
RWFile&
operator<<(RWFile& strm, 
           const RWTPtrHashSet<T,H,EQ,A>  & coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrMap<K,T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, 
           const RWTPtrMultiMap<K,T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrMultiSet<T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrOrderedVector<T,A> &
           coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrSet<T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrSlist<T,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrSortedDlist<T,C,A>&
           coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrSortedVector<T,C,A> &
           coll);
RWFile&
operator<<(RWFile& strm, const RWTValDeque<T,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValDlist<T,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValHashMap<K,T,H,EQ,A>&
           coll);
RWFile&
operator<<(RWFile& strm, 
           const RWTValHashMultiMap<K,T,H,EQ,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValHashSet<T,H,EQ,A>&
           coll);
RWFile&
operator<<(RWFile& strm, const RWTValMap<K,T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValMultiMap<K,T,C,A>&
           coll);
RWFile&
operator<<(RWFile& strm, const RWTValMultiSet<T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValOrderedVector<T,A>&
           coll);
RWFile&
operator<<(RWFile& strm, const RWTValSet<T,C,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValSlist<T,A>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValSortedDlist<T,C,A>&
           coll);
RWFile&
operator<<(RWFile& strm, const RWTValSortedVector& coll);

Saves the collection coll onto the RWFile strm, or a reference to it if it has already been saved.

RWFile&
operator>>(RWFile& strm, RWTPtrDeque<T,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrDlist<T,A>& coll); 
RWFile&
operator>>(RWFile& strm, RWTPtrHashMap<K,T,H,EQ,A>& coll);
RWFile&
operator>>(RWFile& strm, 
           RWTPtrHashMultiMap<K,T,H,EQ,A>& coll);
RWFile&
operator>>(RWFile& strm, 
           RWTPtrHashMultiSet<T,H,EQ,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrHashSet<T,H,EQ,A>  & coll);
RWFile&
operator>>(RWFile& strm, RWTPtrMap<K,T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrMultiMap<K,T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrMultiSet<T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrOrderedVector<T,A> & coll);
RWFile&
operator>>(RWFile& strm, RWTPtrSet<T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrSlist<T,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrSortedDlist<T,C,A>& coll); 
RWFile&
operator>>(RWFile& strm, RWTPtrSortedVector<T,C,A> & coll);
RWFile&
operator>>(RWFile& strm, RWTValDeque<T,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValDlist<T,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValHashMap<K,T,H,EQ,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValHashMultiMap<K,T,H,EQ,A>&
           coll);
RWFile&
operator>>(RWFile& strm, RWTValHashMultiSet<T,H,EQ,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValHashSet<T,H,EQ,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValMap<K,T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValMultiMap<K,T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValMultiSet<T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValOrderedVector<T,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValSet<T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValSlist<T,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValSortedDlist<T,C,A>& coll);
RWFile&
operator>>(RWFile& strm, RWTValSortedVector<T,C,A>& coll);

Restores the contents of the collection coll from the input stream strm.

RWFile&
operator>>(RWFile& strm, RWTPtrDeque<T,A>*& p); 
RWFile&
operator>>(RWFile& strm, RWTPtrDlist<T,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrHashMap<K,T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, 
           RWTPtrHashMultiMap<K,T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, 
           RWTPtrHashMultiSet<T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrHashSet<T,H,EQ,A>  *& p);
RWFile&
operator>>(RWFile& strm, RWTPtrMap<K,T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrMultiMap<K,T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrMultiSet<T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrOrderedVector<T,A> *& p);
RWFile&
operator>>(RWFile& strm, RWTPtrSet<T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrSlist<T,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrSortedDlist<T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrSortedVector<T,C,A> *& p);
RWFile&
operator>>(RWFile& strm, RWTValDeque<T,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValDlist<T,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValHashMap<K,T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValHashMultiMap<K,T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValHashMultiSet<T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValHashSet<T,H,EQ,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValMap<K,T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValMultiMap<K,T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValMultiSet<T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValOrderedVector<T,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValSet<T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValSlist<T,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValSortedDlist<T,C,A>*& p);
RWFile&
operator>>(RWFile& strm, RWTValSortedVector<T,C,A>*& p);

Looks at the next object on the input stream strm and either creates a new collection off the heap and sets p to point to it, or sets p to point to a previously read instance. If a collection is created off the heap, then you are responsible for deleting it.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.