Regina Calculation Engine
Public Member Functions | Protected Attributes
regina::NFile Class Reference

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

#include <file/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.

Internationalisation:
Old-style binary files only support plain ASCII strings. For international character support, new-style XML data files must be used.
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

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

Closes the file.

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

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.

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.

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.
std::streampos regina::NFile::getPosition ( ) [inline]

Returns the current position in the file.

Precondition:
The file is currently open.
Returns:
the current file position.
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:
newResourcethe resource to open.
newOpenModespecifies 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.
Internationalisation:
This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.
Parameters:
fileNamethe pathname of the file to open.
newOpenModespecifies in which mode the file is to be opened. This should be either READ or WRITE.
Returns:
true on success, false on failure.
bool regina::NFile::readBool ( ) [inline]

Reads a bool from file.

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

Reads a boolean set from file.

Precondition:
The file is currently opend for reading.
Returns:
the boolean set read.
char regina::NFile::readChar ( ) [inline]

Reads a character from file.

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

Reads a signed integer from file.

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

Reads an arbitrary precision integer from file.

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

Reads a signed long integer from file.

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

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:
parentthe 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::readPos ( )

Reads a file position from file.

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

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:
readerthe 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).
std::string regina::NFile::readString ( )

Reads a string from file.

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

Reads an unsigned integer from file.

Precondition:
The file is currently opened for reading.
Returns:
the 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.
void regina::NFile::setPosition ( std::streampos  pos) [inline]

Moves to the requested position in the file.

Precondition:
The file is currently open.
Parameters:
posthe position to which to move.
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:
majorthe major version to compare this file with.
minorthe 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.

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::writeBool ( bool  b) [inline]

Writes a bool to file.

Precondition:
The file is currently opened for writing.
Parameters:
bthe 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:
bthe boolean set to write.
void regina::NFile::writeChar ( char  c) [inline]

Writes a character to file.

Precondition:
The file is currently opened for writing.
Parameters:
cthe character to write.
void regina::NFile::writeInt ( int  i)

Writes a signed integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
ithe 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:
ithe arbitrary precision 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:
ithe long integer to write.

Writes the given packet tree to file.

Precondition:
The file is currently opened for writing.
Parameters:
packetthe packet tree to be written to file.
void regina::NFile::writePos ( std::streampos  pos)

Writes a file position to file.

Precondition:
The file is currently opened for writing.
Parameters:
posthe file position to write.
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:
bookmarkthe bookmark returned from the corresponding call to writePropertyHeader().
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.

  • For each property:
    • Call writePropertyHeader(), passing a unique integer (the property type) that indicates which particular property is being written;
    • Write the contents of the property to file (there is no need to write the property type);
    • Call writePropertyFooter(), passing the bookmarking information that was returned from the earlier call to writePropertyHeader().
  • After all properties have been written, call writeAllPropertiesFooter().

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:
propTypethe 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::writeString ( const std::string &  s)

Writes a string to file.

Precondition:
The file is currently opened for writing.
Parameters:
sthe string 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:
outthe output stream to which to write.

Implements regina::ShareableObject.

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

Writes an unsigned integer to file.

Precondition:
The file is currently opened for writing.
Parameters:
ithe 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:
ithe long integer to write.

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-2011, The Regina development team
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).