regina::NFile Class Reference
[File I/O]

Represents an old-style binary file containing a packet tree. More...

#include <nfile.h>

Inheritance diagram for regina::NFile:

regina::ShareableObject regina::boost::noncopyable List of all members.

Public Member Functions

 NFile ()
 Creates a new closed file.
virtual ~NFile ()
 Default destructor.
bool open (NRandomAccessResource *newResource, NRandomAccessResource::mode newOpenMode)
 Opens the requested resource in the requested mode.
bool open (const char *fileName, NRandomAccessResource::mode newOpenMode)
 Opens the requested file in the requested mode.
void close ()
 Closes the file.
NRandomAccessResource::mode getOpenMode () const
 Returns the current state of the file.
int getMajorVersion ()
 Returns the major version number of the engine responsible for this file.
int getMinorVersion ()
 Returns the minor version number of the engine responsible for this file.
bool versionEarlierThan (int major, int minor)
 Determines if this file has a version earlier than the given version.
void writePacketTree (NPacket *packet)
 Writes the given packet tree to file.
NPacketreadPacketTree (NPacket *parent=0)
 Reads a packet tree from file.
std::streampos writePropertyHeader (unsigned propType)
 Writes a header for a property associated with some object.
void writePropertyFooter (std::streampos bookmark)
 Writes a footer for a property associated with some object.
void writeAllPropertiesFooter ()
 Writes a footer indicating that all properties associated with the current object have now been written.
void readProperties (NFilePropertyReader *reader)
 Reads in an entire set of properties associated with some object.
int readInt ()
 Reads a signed integer from file.
unsigned readUInt ()
 Reads an unsigned integer from file.
long readLong ()
 Reads a signed long integer from file.
unsigned long readULong ()
 Reads an unsigned long integer from file.
NLargeInteger readLarge ()
 Reads an arbitrary precision integer from file.
char readChar ()
 Reads a character from file.
std::string readString ()
 Reads a string from file.
bool readBool ()
 Reads a bool from file.
NBoolSet readBoolSet ()
 Reads a boolean set from file.
void writeInt (int i)
 Writes a signed integer to file.
void writeUInt (unsigned i)
 Writes an unsigned integer to file.
void writeLong (long i)
 Writes a signed long integer to file.
void writeULong (unsigned long i)
 Writes an unsigned long integer to file.
void writeLarge (const NLargeInteger &i)
 Writes an arbitrary precision integer to file.
void writeChar (char c)
 Writes a character to file.
void writeString (const std::string &s)
 Writes a string to file.
void writeBool (bool b)
 Writes a bool to file.
void writeBoolSet (const NBoolSet &b)
 Writes a boolean set to file.
std::streampos getPosition ()
 Returns the current position in the file.
void setPosition (std::streampos pos)
 Moves to the requested position in the file.
std::streampos readPos ()
 Reads a file position from file.
void writePos (std::streampos pos)
 Writes a file position to file.
void writeTextShort (std::ostream &out) const
 Writes this object in short text format to the given output stream.

Protected Attributes

int majorVersion
 Major version number of the engine that wrote this file.
int minorVersion
 Minor version number of the engine that wrote this file.

Detailed Description

Represents an old-style binary file containing a packet tree.

Provides routines for opening, closing, reading and writing.

Deprecated:
The preferred way of representing data is using XML which is accessed using text I/O streams.
Python:
Not present.


Constructor & Destructor Documentation

regina::NFile::NFile (  )  [inline]

Creates a new closed file.

regina::NFile::~NFile (  )  [inline, virtual]

Default destructor.

Ensures that the file is closed.


Member Function Documentation

bool regina::NFile::open ( NRandomAccessResource newResource,
NRandomAccessResource::mode  newOpenMode 
)

Opens the requested resource in the requested mode.

If the resource is to be opened for reading, it will fail if the resource does not exist. If the resource is to be opened for writing, it will delete any existing resource contents.

This NFile will be responsible for destroying the given resource newResource, whether or not the open succeeds. It should not be destroyed elsewhere.

Precondition:
This file is currently closed.
Parameters:
newResource the resource to open.
newOpenMode specifies in which mode the resource is to be opened. This should be either READ or WRITE.
Returns:
true on success, false on failure.

bool regina::NFile::open ( const char *  fileName,
NRandomAccessResource::mode  newOpenMode 
)

Opens the requested file in the requested mode.

If the file is to be opened for reading, it will fail if the file does not exist. If the file is to be opened for writing, it will delete any existing file contents.

Precondition:
This file is currently closed.
Parameters:
fileName the pathname of the file to open.
newOpenMode specifies in which mode the file is to be opened. This should be either READ or WRITE.
Returns:
true on success, false on failure.

void regina::NFile::close (  )  [inline]

Closes the file.

If the file is already closed, this routine will do nothing.

NRandomAccessResource::mode regina::NFile::getOpenMode (  )  const [inline]

Returns the current state of the file.

If the file is open, the mode in which it was opened will be returned (either READ or WRITE). If the file is closed, 0 (alternatively, CLOSED) will be returned.

Returns:
the current state of the file.

int regina::NFile::getMajorVersion (  )  [inline]

Returns the major version number of the engine responsible for this file.

If the file is open for reading, this will be the number of the engine that wrote the file. If the file is open for writing, this will be the number of this engine.

Precondition:
The file is currently open.
Returns:
the major version number.

int regina::NFile::getMinorVersion (  )  [inline]

Returns the minor version number of the engine responsible for this file.

If the file is open for reading, this will be the number of the engine that wrote the file. If the file is open for writing, this will be the number of this engine.

Precondition:
The file is currently open.
Returns:
the minor version number.

bool regina::NFile::versionEarlierThan ( int  major,
int  minor 
) [inline]

Determines if this file has a version earlier than the given version.

This routine will return false if the versions are identical.

Parameters:
major the major version to compare this file with.
minor the minor version to compare this file with.
Returns:
true if and only if the version of this file is earlier than the given major-minor combination.

void regina::NFile::writePacketTree ( NPacket packet  ) 

Writes the given packet tree to file.

Precondition:
The file is currently opened for writing.
Parameters:
packet the packet tree to be written to file.

NPacket* regina::NFile::readPacketTree ( NPacket parent = 0  ) 

Reads a packet tree from file.

This routine can also be used to read a packet subtree.

Any packets encountered of unknown type will be skipped, along with their descendants. If an individual packet read routine runs into problems or reads in the wrong amount of data, this will not affect other packets in the overall tree aside from descendants of the problematic packet.

Precondition:
The file is currently opened for reading.
Parameters:
parent the packet that will become the parent of the new subtree being read, or 0 if an entire packet tree is being read. Note that the subtree being read might or might not be inserted as a child of parent; this information is provided mainly for reference.
Returns:
the packet tree read from file, or 0 if problems were encountered with the highest level packet in the tree.

std::streampos regina::NFile::writePropertyHeader ( unsigned  propType  ) 

Writes a header for a property associated with some object.

This header will include the given property type as well as some bookmarking details. The bookmark returned should later be passed to writePropertyFooter() for housekeeping.

If some set of properties is to be stored for some object, the procedure for writing properties to a file is as follows.

This allows an NFilePropertyReader to read the properties from file in a manner independent of which version of Regina was originally used to create the file. In particular, properties of unknown type can simply be ignored, and errors in reading individual properties can be gracefully overcome.

To read a set of properties that has been stored for some object, call readProperties() with an NFilePropertyReader that understands the different potential property types.

Precondition:
The file is currently opened for writing.
Parameters:
propType the property type to write in the property header; this must be strictly positive.
Returns:
bookmarking information that should later be passed to writePropertyFooter().

void regina::NFile::writePropertyFooter ( std::streampos  bookmark  ) 

Writes a footer for a property associated with some object.

See the writePropertyHeader() notes for details about writing object properties to file.

Precondition:
The file is currently opened for writing.
Parameters:
bookmark the bookmark returned from the corresponding call to writePropertyHeader().

void regina::NFile::writeAllPropertiesFooter (  ) 

Writes a footer indicating that all properties associated with the current object have now been written.

See the writePropertyHeader() notes for details about writing object properties to file.

Precondition:
The file is currently opened for writing.

void regina::NFile::readProperties ( NFilePropertyReader reader  ) 

Reads in an entire set of properties associated with some object.

These properties must have been written using the mechanism described in the writePropertyHeader() notes.

Note that different types of properties may have been written to file, some of which can be understood and some of which cannot (since a different version of Regina may have been used to originally write the file). Properties that cannot be understood will simply be ignored. If errors occur whilst reading properties that can be understood, these errors will be gracefully overcome.

The property reader that is passed is responsible for declaring which property types are recognised as well as reading and processing individual properties of recognised types.

Once this routine has finished the current position in the file will be after the final property footer as written by writeAllPropertiesFooter().

Precondition:
The file is currently opened for reading.
Parameters:
reader the property reader responsible for reading individual properties. This may be 0, in which case all properties will be ignored (though the current file position will still be adjusted as described above).

int regina::NFile::readInt (  ) 

Reads a signed integer from file.

Precondition:
The file is currently opened for reading.
Returns:
the integer read.

unsigned regina::NFile::readUInt (  ) 

Reads an unsigned integer from file.

Precondition:
The file is currently opened for reading.
Returns:
the integer read.

long regina::NFile::readLong (  ) 

Reads a signed long integer from file.

Precondition:
The file is currently opened for reading.
Returns:
the long integer read.

unsigned long regina::NFile::readULong (  ) 

Reads an unsigned long integer from file.

Precondition:
The file is currently opened for reading.
Returns:
the long integer read.

NLargeInteger regina::NFile::readLarge (  )  [inline]

Reads an arbitrary precision integer from file.

Precondition:
The file is currently opened for reading.
Returns:
the arbitrary precision integer read.

char regina::NFile::readChar (  )  [inline]

Reads a character from file.

Precondition:
The file is currently opened for reading.
Returns:
the character read.

std::string regina::NFile::readString (  ) 

Reads a string from file.

Precondition:
The file is currently opened for reading.
Returns:
the string read.

bool regina::NFile::readBool (  )  [inline]

Reads a bool from file.

Precondition:
The file is currently opend for reading.
Returns:
the bool read.

NBoolSet regina::NFile::readBoolSet (  )  [inline]

Reads a boolean set from file.

Precondition:
The file is currently opend for reading.
Returns:
the boolean set read.

void regina::NFile::writeInt ( int  i  ) 

Writes a signed integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
i the integer to write.

void regina::NFile::writeUInt ( unsigned  i  ) 

Writes an unsigned integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
i the integer to write.

void regina::NFile::writeLong ( long  i  ) 

Writes a signed long integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
i the long integer to write.

void regina::NFile::writeULong ( unsigned long  i  ) 

Writes an unsigned long integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
i the long integer to write.

void regina::NFile::writeLarge ( const NLargeInteger i  )  [inline]

Writes an arbitrary precision integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
i the arbitrary precision integer to write.

void regina::NFile::writeChar ( char  c  )  [inline]

Writes a character to file.

Precondition:
The file is currently opened for writing.
Parameters:
c the character to write.

void regina::NFile::writeString ( const std::string &  s  ) 

Writes a string to file.

Precondition:
The file is currently opened for writing.
Parameters:
s the string to write.

void regina::NFile::writeBool ( bool  b  )  [inline]

Writes a bool to file.

Precondition:
The file is currently opened for writing.
Parameters:
b the bool to write.

void regina::NFile::writeBoolSet ( const NBoolSet b  )  [inline]

Writes a boolean set to file.

Precondition:
The file is currently opened for writing.
Parameters:
b the boolean set to write.

std::streampos regina::NFile::getPosition (  )  [inline]

Returns the current position in the file.

Precondition:
The file is currently open.
Returns:
the current file position.

void regina::NFile::setPosition ( std::streampos  pos  )  [inline]

Moves to the requested position in the file.

Precondition:
The file is currently open.
Parameters:
pos the position to which to move.

std::streampos regina::NFile::readPos (  ) 

Reads a file position from file.

Precondition:
The file is currently opened for reading.
Returns:
the file position read.

void regina::NFile::writePos ( std::streampos  pos  ) 

Writes a file position to file.

Precondition:
The file is currently opened for writing.
Parameters:
pos the file position to write.

void regina::NFile::writeTextShort ( std::ostream &  out  )  const [virtual]

Writes this object in short text format to the given output stream.

The output should fit on a single line and no newline should be written.

Python:
The parameter out does not exist; standard output will be used.
Parameters:
out the output stream to which to write.

Implements regina::ShareableObject.


Member Data Documentation

int regina::NFile::majorVersion [protected]

Major version number of the engine that wrote this file.

int regina::NFile::minorVersion [protected]

Minor version number of the engine that wrote this file.


The documentation for this class was generated from the following file:
Copyright © 1999-2006, Ben Burton
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).