Foreign File Formats

Reading and writing foreign file formats. More...

Functions
std::shared_ptr< Container >	regina::readDehydrationList (const char *filename, unsigned colDehydrations=0, int colLabels=-1, unsigned long ignoreLines=0)
	Reads a list of dehydrated triangulations from the given text file. More...
template<class PacketType >
std::shared_ptr< Container >	regina::readSigList (const char *filename, unsigned colSigs=0, int colLabels=-1, unsigned long ignoreLines=0)
	Reads a list of isomorphism signatures or knot signatures from the given text file. More...
std::shared_ptr< Container >	regina::readIsoSigList (const char *filename, unsigned dimension=3, unsigned colSigs=0, int colLabels=-1, unsigned long ignoreLines=0)
	A deprecated weaker version of readSigList(), which reads a list of isomorphism signatures for triangulations from the given text file. More...
std::shared_ptr< PacketOf< Triangulation< 3 > > >	regina::readOrb (const char *filename)
	Reads a triangulation from the given Orb / Casson file. More...

Detailed Description

Reading and writing foreign file formats.

Function Documentation

readDehydrationList()

std::shared_ptr< Container > regina::readDehydrationList	(	const char *	filename,
		unsigned	colDehydrations = 0,
		int	colLabels = -1,
		unsigned long	ignoreLines = 0
	)

Reads a list of dehydrated triangulations from the given text file.

The file should contain one dehydration string per line. These strings will be rehydrated as described in Triangulation<3>::rehydrate().

A new container will be returned; the imported triangulations will be inserted as children of this container. The container will not be assigned a label. The individual triangulations will be assigned labels according to the parameter colLabels.

If any dehydrations strings are invalid, these will be recorded in an additional text packet that will be the last child of the returned container.

If an I/O error occurred while trying to read the given file, 0 will be returned.

In its simplest form, the text file can simply contain one dehydration string per line and nothing else. However, more complex formats are allowed. In particular, by passing appropriate values for the arguments colDehydrations and colLabels, the dehydration strings and triangulation packet labels can be taken from arbitrary columns of the text file. Columns are considered to be separated by whitespace and are numbered beginning at 0.

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. It assumes however that the contents of the file are in UTF-8.

Parameters

filename	the name of the text file from which to read.
colDehydrations	the column of the text file containing the dehydration strings.
colLabels	the column of the text file containing the triangulation packet labels. If this is negative then the dehydration strings themselves will be used as packet labels.
ignoreLines	the number of lines at the beginning of the text file that should be ignored completely.

Returns

a new container as described above, or null if an I/O error occurred whilst reading the given file.

readIsoSigList()

std::shared_ptr< Container > regina::readIsoSigList	(	const char *	filename,
		unsigned	dimension = 3,
		unsigned	colSigs = 0,
		int	colLabels = -1,
		unsigned long	ignoreLines = 0
	)

A deprecated weaker version of readSigList(), which reads a list of isomorphism signatures for triangulations from the given text file.

Unlike readSigList() (which is more general), this function can only work with 2-manifold, 3-manifold and 4-manifold triangulations.

Also, unlike readSigList(), this is not a template function. Instead of the template argument PacketType used by readSigList() to indicate what kind of object to construct, this function has an additional dimension parameter.

See readSigList() for further details on what this routine does.

Deprecated:

Use readSigList<Triangulation<2>>, readSigList<Triangulation<3>> or readSigList<Triangulation<4>> instead.

Parameters

filename	the name of the text file from which to read.
dimension	either 2, 3 or 4, indicating whether isomorphism signatures should be expanded into 2-manifold, 3-manifold or 4-manifold triangulations respectively.
colSigs	the column of the text file containing the signatures.
colLabels	the column of the text file containing the packet labels for the resulting triangulations. If this is negative then the signatures themselves will be used as packet labels.
ignoreLines	the number of lines at the beginning of the text file that should be ignored completely.

Returns

a new container, or null if an I/O error occurred whilst reading the given file.

readOrb()

std::shared_ptr< PacketOf< Triangulation< 3 > > > regina::readOrb

(

const char *

filename

)

Reads a triangulation from the given Orb / Casson file.

A new triangulation packet will be returned.

The packet label of the new triangulation will be the manifold name read from the second line of the Orb / Casson file. The first line of the Orb / Casson file must simply be `‘% orb’'.

If the file could not be read or if the data was not in the correct format, null will be returned.

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. It assumes however that the contents of the file are in UTF-8.

Parameters

filename

the name of the Orb / Casson file from which to read.

Returns

a new triangulation packet containing the data read from the Orb / Casson file, or null on error.

Author

Ryan Budney, also with code from Damien Heard

readSigList()

template<class PacketType >

std::shared_ptr< Container > regina::readSigList	(	const char *	filename,
		unsigned	colSigs = 0,
		int	colLabels = -1,
		unsigned long	ignoreLines = 0
	)

Reads a list of isomorphism signatures or knot signatures from the given text file.

The file should contain one signature per line. Signatures for knots or triangulations of any dimension are all accepted, though the type of object must be known in advance and fixed for the entire function call using the template parameter PacketType. These signatures will be converted into knots and/or triangulations using Link::fromKnotSig() and Triangulation<dim>::fromIsoSig() respectively.

A new container will be returned; the imported knots or triangulations will be inserted as children of this container. The container will not be assigned a label. The individual knots or triangulations will be assigned labels according to the parameter colLabels.

If any signatures are invalid, these will be recorded in an additional text packet that will be the last child of the returned container.

If an I/O error occurred while trying to read the given file, null will be returned.

In its simplest form, the text file can simply contain one signature per line and nothing else. However, more complex formats are allowed. In particular, by passing appropriate values for the arguments colSigs and colLabels, the signatures and packet labels can be taken from arbitrary columns of the text file. Columns are considered to be separated by whitespace and are numbered beginning at 0.

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. It assumes however that the contents of the file are in UTF-8.

Template Parameters

PacketType

Indicates which types of signatures the file contains. This must be either Link (indicating that the file contains knot signatures), or one of the Triangulation<dim> classes (indicating that the file contains isomorphism signatures for dim-dimensional triangulations).

Python

Since Python does not support templates, the Python version of this function takes an extra first parameter dimension. This should be the dimension of the underlying triangulation type, or 0 to indicate that we are working with knot signatures. Moreover, the Python version currently only supports Regina's standard dimensions (i.e., you cannot use the Python version of this function with triangulations of dimension 5 or higher).

Parameters

filename	the name of the text file from which to read.
colSigs	the column of the text file containing the signatures.
colLabels	the column of the text file containing the packet labels for the resulting knots or triangulations. If this is negative then the signatures themselves will be used as packet labels.
ignoreLines	the number of lines at the beginning of the text file that should be ignored completely.

Returns

a new container as described above, or null if an I/O error occurred whilst reading the given file.