Foreign File Formats

Reading and writing foreign file formats. More...

## Functions

REGINA_API bool | regina::writeCSVStandard (const char *filename, NNormalSurfaceList &surfaces, int additionalFields=surfaceExportAll)
| Deprecated function that exports the given list of normal surfaces as a plain text CSV (comma-separated value) file, using standard triangle-quadrilateral coordinates. More...
REGINA_API bool | regina::writeCSVEdgeWeight (const char *filename, NNormalSurfaceList &surfaces, int additionalFields=surfaceExportAll)
| Deprecated function that exports the given list of normal surfaces as a plain text CSV (comma-separated value) file, using edge weight coordinates. More...
REGINA_API NContainer * | 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...
REGINA_API NContainer * | regina::readIsoSigList (const char *filename, unsigned dimension=3, unsigned colSigs=0, int colLabels=-1, unsigned long ignoreLines=0)
| Reads a list of isomorphism signatures from the given text file. More...
REGINA_API NTriangulation * | regina::readOrb (const char *filename)
| Reads a triangulation from the given Orb / Casson file. More...
REGINA_API NPDF * | regina::readPDF (const char *filename)
| Deprecated function that reads a PDF document from the given file. More...
REGINA_API bool | regina::writePDF (const char *filename, const NPDF &pdf)
| Deprecated function that writes the given PDF document to the given file. More...
REGINA_API bool | regina::writeRecogniser (const char *filename, NTriangulation &tri)
| Deprecated function that writes the given triangulation to the given file in Matveev's 3-manifold recogniser format. More...
REGINA_API bool | regina::writeRecognizer (const char *filename, NTriangulation &tri)
| Deprecated function that writes the given triangulation to the given file in Matveev's 3-manifold recogniser format. More...
REGINA_API NTriangulation * | regina::readSnapPea (const char *filename)
| Deprecated function that reads the given SnapPea data file and converts the result to Regina's NTriangulation class (thereby losing some SnapPea-specific information in the process). More...
REGINA_API NTriangulation * | regina::readSnapPea (std::istream &in)
| Deprecated function that reads the contents of a SnapPea data file from the given input stream, and converts the result to Regina's NTriangulation class (thereby losing some SnapPea-specific information in the process). More...
REGINA_API bool | regina::writeSnapPea (const char *filename, const NTriangulation &tri)
| Deprecated function that writes the given triangulation to the given file using SnapPea's native file format. More...
REGINA_API void | regina::writeSnapPea (std::ostream &out, const NTriangulation &tri)
| Deprecated function that writes the given triangulation to the given output stream using SnapPea's native file format. More...

## Detailed Description

Reading and writing foreign file formats.

## Function Documentation

REGINA_API NContainer* 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 NTriangulation::insertRehydration().

A newly allocated 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 0 if an I/O error occurred whilst reading the given file.

REGINA_API NContainer* regina::readIsoSigList | ( | const char * | filename,
|  | unsigned | dimension = `3`,
|  | unsigned | colSigs = `0`,
|  | int | colLabels = `-1`,
|  | unsigned long | ignoreLines = `0`
| ) |  |

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

The file should contain one isomorphism signature per line. These isomorphism signatures will be converted into triangulations using NTriangulation::fromIsoSig().

A newly allocated 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 isomorphism 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, 0 will be returned.

In its simplest form, the text file can simply contain one isomorphism 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 isomorphism signatures 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.
  dimension | must be set to 3, indicating that isomorphism signatures should be expanded into 3-manifold triangulations. This argument is a placeholder for future expansion, and currently no value other than 3 is allowed.
  colSigs | the column of the text file containing the isomorphism signatures.
  colLabels | the column of the text file containing the triangulation packet labels. If this is negative then the isomorphism 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 0 if an I/O error occurred whilst reading the given file.

REGINA_API NTriangulation* regina::readOrb | ( | const char * | filename | ) |

Reads a triangulation from the given Orb / Casson file.

A newly allocated triangulation will be returned; it is the user's responsibility to deallocate this when it is finished with.

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, 0 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 containing the data read from the Orb / Casson file, or 0 on error.

Author
  Ryan Budney, also with code from Damien Heard

REGINA_API NPDF* regina::readPDF | ( | const char * | filename | ) |

Deprecated function that reads a PDF document from the given file.

If the file could not be read, or if the file is empty, then 0 will be returned. Otherwise a newly allocated PDF packet will be returned, and it is the user's responsibility to deallocate this when it is finished with.

Deprecated:
  You should use the NPDF constructor NPDF::NPDF(const char*), and you should pass the filename as the single string argument. In situations where this routine would have returned a null pointer, the NPDF constructor will instead create a null document (i.e., one for which NPDF::isNull() returns `true`). See the NPDF constructor for further details.

REGINA_API NTriangulation* regina::readSnapPea | ( | const char * | filename | ) |

Deprecated function that reads the given SnapPea data file and converts the result to Regina's NTriangulation class (thereby losing some SnapPea-specific information in the process).

If the file could not be read or if the data was not in the correct format, 0 will be returned. Otherwise a newly allocated triangulation will be returned, and it is the user's responsibility to deallocate this when it is finished with.

Deprecated:
  You should use the NSnapPeaTriangulation constructor NSnapPeaTriangulation::NSnapPeaTriangulation(const std::string&) instead. In situations where this routine would have returned a null pointer, the NSnapPeaTriangulation constructor will instead create a null triangulation (i.e., one for which isNull() returns `true`). See the NSnapPeaTriangulation constructor for further details.

Warning
  Since this routine returns an NTriangulation (Regina's native data type), it will lose any SnapPea-specific information (such as peripheral curves). It is strongly recommended that you use the NSnapPeaTriangulation constructor instead (as described above), since this will return an NSnapPeaTriangulation object that preserves SnapPea's additional data.

REGINA_API NTriangulation* regina::readSnapPea | ( | std::istream & | in | ) |

Deprecated function that reads the contents of a SnapPea data file from the given input stream, and converts the result to Regina's NTriangulation class (thereby losing some SnapPea-specific information in the process).

If the input stream could not be read or if the data was not in the correct format, 0 will be returned. Otherwise a newly allocated triangulation will be returned, and it is the user's responsibility to deallocate this when it is finished with.

Deprecated:
  You should use the NSnapPeaTriangulation constructor NSnapPeaTriangulation::NSnapPeaTriangulation(const std::string&) instead (you will need to pass the contents of the input stream, not the input stream itself). In situations where this routine would have returned a null pointer, the NSnapPeaTriangulation constructor will instead create a null triangulation (i.e., one for which isNull() returns `true`). See the NSnapPeaTriangulation constructor for further details.

Warning
  Since this routine returns an NTriangulation (Regina's native data type), it will lose any SnapPea-specific information (such as peripheral curves). It is strongly recommended that you use the NSnapPeaTriangulation constructor instead (as described above), since this will return an NSnapPeaTriangulation object that preserves SnapPea's additional data.

Python:
  Not present.

bool regina::writeCSVEdgeWeight | ( | const char * | filename,
|  | NNormalSurfaceList & | surfaces,
|  | int | additionalFields = `surfaceExportAll`
| ) |  |

inline

Deprecated function that exports the given list of normal surfaces as a plain text CSV (comma-separated value) file, using edge weight coordinates.

Deprecated:
  This routine has been renamed as NNormalSurfaceList::saveCSVEdgeWeight(). See the documentation for NNormalSurfaceList::saveCSVEdgeWeight() for further details.

bool regina::writeCSVStandard | ( | const char * | filename,
|  | NNormalSurfaceList & | surfaces,
|  | int | additionalFields = `surfaceExportAll`
| ) |  |

inline

Deprecated function that exports the given list of normal surfaces as a plain text CSV (comma-separated value) file, using standard triangle-quadrilateral coordinates.

Deprecated:
  This routine has been renamed as NNormalSurfaceList::saveCSVStandard(). See the documentation for NNormalSurfaceList::saveCSVStandard() for further details.

REGINA_API bool regina::writePDF | ( | const char * | filename,
|  | const NPDF & | pdf
| ) |  |

Deprecated function that writes the given PDF document to the given file.

Deprecated:
  This routine has been renamed as NPDF::savePDF(). This old routine behaves exactly as in the past, but the new NPDF::savePDF() has a slight change in behaviour: if the PDF packet contains no data then it no longer creates an empty file, but instead does nothing and returns `false`. See NPDF::savePDF() for further details.

bool regina::writeRecogniser | ( | const char * | filename,
|  | NTriangulation & | tri
| ) |  |

inline

Deprecated function that writes the given triangulation to the given file in Matveev's 3-manifold recogniser format.

Deprecated:
  This routine has been renamed as NTriangulation::saveRecogniser(). This old routine behaves exactly as in the past, but the new NTriangulation::saveRecogniser() has a slight change of behaviour: unlike the old routine, it now requires a non-empty filename. To send data to standard output (as in the old routine), you may call NTriangulation::recogniser() and simply print the resulting string. See the NTriangulation::saveRecogniser() documentation for further details.

bool regina::writeRecognizer | ( | const char * | filename,
|  | NTriangulation & | tri
| ) |  |

inline

Deprecated function that writes the given triangulation to the given file in Matveev's 3-manifold recogniser format.

Deprecated:
  This routine has been renamed as NTriangulation::saveRecogniser(). This old routine behaves exactly as in the past, but the new NTriangulation::saveRecogniser() has a slight change of behaviour: unlike the old routine, it now requires a non-empty filename. To send data to standard output (as in the old routine), you may call NTriangulation::recogniser() and simply print the resulting string. See the NTriangulation::saveRecogniser() documentation for further details.

REGINA_API bool regina::writeSnapPea | ( | const char * | filename,
|  | const NTriangulation & | tri
| ) |  |

Deprecated function that writes the given triangulation to the given file using SnapPea's native file format.

Deprecated:
  This routine has been renamed as NTriangulation::saveSnapPea(). See the documentation of NTriangulation::saveSnapPea() for further details.

REGINA_API void regina::writeSnapPea | ( | std::ostream & | out,
|  | const NTriangulation & | tri
| ) |  |

Deprecated function that writes the given triangulation to the given output stream using SnapPea's native file format.

Deprecated:
  This routine has been renamed as NTriangulation::snapPea(std::ostream&). See the documentation for NTriangulation::snapPea(std::ostream&) for further information.

Python:
  Not present.

Copyright © 1999-2014, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).