Regina Calculation Engine
Classes | Defines | Functions
File I/O

File reading and writing. More...

Classes

class  regina::NFile
 Represents an old-style binary file containing a packet tree. More...
class  regina::NFileInfo
 Stores information about a Regina data file, including file type and version. More...
class  regina::NFilePropertyReader
 Assists with reading individual object properties from old-style binary data files. More...
class  regina::NGlobalDirs
 Provides global routines that return directories in which various components of Regina are installed on the system. More...
class  regina::NRandomAccessResource
 Provides a standard random access interface for old-style binary file-like resources. More...
class  regina::NLocalFileResource
 A random access resource that is simply a local file. More...
class  regina::NXMLCallback
 Provides the callbacks for an XMLParser required to parse an entire file using a series of NXMLElementReader objects. More...
class  regina::NXMLElementReader
 Used to read the contents of a single XML element. More...
class  regina::NXMLCharsReader
 A reader for an XML element that contains only characters. More...

Defines

#define NFILE_PROGRAM_NAME   "Regina"
 String name of the program, to be placed at the beginning of data files.
#define NFILE_SIZE_INT   4
 The number of bytes written to files to represent an integer; any higher order bytes will be ignored.
#define NFILE_SIZE_LONG   8
 The number of bytes written to files to represent a long integer; any higher order bytes will be ignored.
#define NFILE_SIZE_FILEPOS   8
 The number of bytes written to files to represent a file position; any higher order bytes will be ignored.

Functions

NPacket * regina::readFromFile (const char *fileName)
 Reads a packet tree from the given old-style binary file doing everything in a single step.
bool regina::writeToFile (const char *fileName, NPacket *packet)
 Writes the given packet tree to the given old-style binary file doing everything in a single step.
bool regina::writeXMLFile (const char *fileName, NPacket *subtree, bool compressed=true)
 Writes the subtree with the given packet as matriarch to disk as a complete XML file.
NPacket * regina::readXMLFile (const char *fileName)
 Reads the packet tree stored in the given XML file.
NPacket * regina::readFileMagic (const std::string &fileName)
 Reads a packet tree from a file whose format is unknown.

Detailed Description

File reading and writing.


Define Documentation

#define NFILE_PROGRAM_NAME   "Regina"

String name of the program, to be placed at the beginning of data files.

#define NFILE_SIZE_FILEPOS   8

The number of bytes written to files to represent a file position; any higher order bytes will be ignored.

This ensures constancy of file format across platforms.

#define NFILE_SIZE_INT   4

The number of bytes written to files to represent an integer; any higher order bytes will be ignored.

This ensures constancy of file format across platforms.

#define NFILE_SIZE_LONG   8

The number of bytes written to files to represent a long integer; any higher order bytes will be ignored.

This ensures constancy of file format across platforms.


Function Documentation

NPacket* regina::readFileMagic ( const std::string &  fileName)

Reads a packet tree from a file whose format is unknown.

The file may be in either XML (optionally compressed) or old-style binary format.

If the matriarch of the packet tree could not be read, this routine will return 0. If a lower-level packet could not be read, it (and its descendants) will simply be ignored.

The given file will almost certainly be opened and closed multiple times during this routine.

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 read from.
Returns:
the packet tree read from file, or 0 if problems were encountered or the file could not be opened.
NPacket* regina::readFromFile ( const char *  fileName)

Reads a packet tree from the given old-style binary file doing everything in a single step.

This routine reads the complete packet tree from the given file. If the highest level packet could not be read, this routine will return null. The behaviour regarding problematic subpackets is identical to that of NFile::readPacketTree().

Internationalisation:
Old-style binary files only support plain ASCII strings. For international character support, new-style XML data files must be used. Also, 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.
Deprecated:
The preferred way of representing data is using XML which is accessed using text I/O streams. See routines readXMLFile() and readFileMagic() for corresponding XML all-at-once read routines.
Python:
Not present.
Parameters:
fileNamethe pathname of the file to read from.
Returns:
the packet tree read from file, or null if problems were encountered or the file could not be opened.
NPacket* regina::readXMLFile ( const char *  fileName)

Reads the packet tree stored in the given XML file.

It does not matter whether the XML file is compressed.

If the matriarch of the packet tree could not be read, this routine will return 0. If a lower-level packet could not be read, it (and its descendants) will simply be ignored.

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 read from.
Returns:
the packet tree read from file, or 0 if problems were encountered or the file could not be opened.
bool regina::writeToFile ( const char *  fileName,
NPacket *  packet 
)

Writes the given packet tree to the given old-style binary file doing everything in a single step.

Internationalisation:
Old-style binary files only support plain ASCII strings. For international character support, new-style XML data files must be used. Also, 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.
Deprecated:
The preferred way of representing data is using XML which is accessed using text I/O streams. See routine writeXMLFile() for a corresponding XML all-at-once write routine.
Python:
Not present.
Parameters:
fileNamethe pathname of the file to write to.
packetthe packet tree to write to file.
Returns:
true if and only if the packet tree was successfully written.
bool regina::writeXMLFile ( const char *  fileName,
NPacket *  subtree,
bool  compressed = true 
)

Writes the subtree with the given packet as matriarch to disk as a complete XML file.

The XML file may be optionally compressed.

This is the preferred way of writing a packet tree to file.

Precondition:
The given packet does not depend on its parent.
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 write to.
subtreethe matriarch of the packet tree that should be written.
compressedtrue if the XML file should be compressed or false if it should be stored as plain text.
Returns:
true if and only if the packet subtree was successfully written.

Copyright © 1999-2009, 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).