Stores information about a Regina data file, including file format and version. More...

#include <file/fileinfo.h>

Inheritance diagram for regina::FileInfo:

Public Member Functions
	FileInfo (const FileInfo &)=default
	Creates a new copy of the given file information. More...

	FileInfo (FileInfo &&) noexcept=default
	Moves the contents of the given file information to this new object. More...

const std::string &	pathname () const
	Returns the pathname of the data file being described. More...

FileFormat	format () const
	Returns which of Regina's file formats the data file uses. More...

std::string	formatDescription () const
	Returns a human-readable description of the file format used by the data file. More...

const std::string &	engine () const
	Returns the version of the calculation engine that wrote this file. More...

bool	isCompressed () const
	Returns whether this file is stored in compressed format. More...

bool	isInvalid () const
	Returns whether the file metadata could not be read. More...

FileInfo &	operator= (const FileInfo &)=default
	Sets this to be a copy of the given file information. More...

FileInfo &	operator= (FileInfo &&) noexcept=default
	Moves the contents of the given file information to this new object. More...

void	swap (FileInfo &other) noexcept
	Swaps the contents of this and the given file information. More...

bool	operator== (const FileInfo &other) const
	Determines whether this and the given file information describe the same format and version. More...

bool	operator!= (const FileInfo &other) const
	Determines whether this and the given file information do not describe the same format and version. More...

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream. More...

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream. More...

std::string	str () const
	Returns a short text representation of this object. More...

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters. More...

std::string	detail () const
	Returns a detailed text representation of this object. More...

Static Public Member Functions
static std::optional< FileInfo >	identify (std::string idPathname)
	Return information about the given Regina data file. More...

Detailed Description

Stores information about a Regina data file, including file format and version.

Routine identify() can be used to determine this information for a given file.

As of Regina 4.94, the ancient first-generation binary files (REGINA_BINARY_GEN_1) are no longer supported, and this class cannot recognise them at all. These have not been in use since mid-2002. The only file formats that this class now recognises are Regina's newer XML-based (compressed or uncompressed) data files.

This class implements C++ move semantics and adheres to the C++ Swappable requirement, though it does not implement (or need) its own custom swap() function. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Constructor & Destructor Documentation

◆ FileInfo() [1/2]

regina::FileInfo::FileInfo ( const FileInfo & )

default

Creates a new copy of the given file information.

◆ FileInfo() [2/2]

regina::FileInfo::FileInfo ( FileInfo && )

defaultnoexcept

Moves the contents of the given file information to this new object.

The object that was passed will no longer be usable.

Member Function Documentation

◆ detail()

std::string regina::Output< FileInfo , false >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ engine()

const std::string & regina::FileInfo::engine ( ) const

inline

Returns the version of the calculation engine that wrote this file.

Returns: the engine version for this file.

◆ format()

FileFormat regina::FileInfo::format ( ) const

inline

Returns which of Regina's file formats the data file uses.

In particular, this encodes which generation of XML the file uses, but does not encode whether the XML is compressed.

Returns: the file format.

◆ formatDescription()

std::string regina::FileInfo::formatDescription ( ) const

inline

Returns a human-readable description of the file format used by the data file.

Like format(), this indicates which generation of XML the file uses, but not whether the XML is compressed.

Returns: a description of the file format.

◆ identify()

static std::optional< FileInfo > regina::FileInfo::identify ( std::string idPathname )

static

Return information about the given Regina data file.

Internationalisation: This routine makes no assumptions about the character encoding used in the given path name, and simply passes it through unchanged to low-level C/C++ file I/O routines. If a FileInfo structure is returned, its pathname() routine will use the same encoding that is passed here.

Parameters

idPathname the pathname of the data file to be examined.

Returns: a FileInfo structure containing information about the given file, or no value if the file type could not be identified.

◆ isCompressed()

bool regina::FileInfo::isCompressed ( ) const

inline

Returns whether this file is stored in compressed format.

Currently this option only applies to XML data files.

Returns: true if this file is compressed or false otherwise.

◆ isInvalid()

bool regina::FileInfo::isInvalid ( ) const

inline

Returns whether the file metadata could not be read.

Returns: true if the metadata could not be read, false otherwise.

◆ operator!=()

bool regina::FileInfo::operator!= ( const FileInfo & other ) const

inline

Determines whether this and the given file information do not describe the same format and version.

For two FileInfo objects to compare as equal, they must have the same file formats, use the same version of the calculation engine, and use the same compression type. The pathnames of the files being described are ignored.

It is safe to compare FileInfo objects even if one or both is invalid. Two invalid FileInfo objects will compare as equal.

Parameters

other the file information to compare with this.

Returns: true if and only if this and the given file information do not describe the same format and version, as described above.

◆ operator=() [1/2]

FileInfo & regina::FileInfo::operator= ( const FileInfo & )

default

Sets this to be a copy of the given file information.

◆ operator=() [2/2]

FileInfo & regina::FileInfo::operator= ( FileInfo && )

defaultnoexcept

Moves the contents of the given file information to this new object.

The object that was passed will no longer be usable.

Returns: a reference to this object.

◆ operator==()

bool regina::FileInfo::operator== ( const FileInfo & other ) const

inline

Determines whether this and the given file information describe the same format and version.

For two FileInfo objects to compare as equal, they must have the same file formats, use the same version of the calculation engine, and use the same compression type. The pathnames of the files being described are ignored.

It is safe to compare FileInfo objects even if one or both is invalid. Two invalid FileInfo objects will compare as equal.

Parameters

other the file information to compare with this.

Returns: true if and only if this and the given file information describe the same format and version, as described above.

◆ pathname()

const std::string & regina::FileInfo::pathname ( ) const

inline

Returns the pathname of the data file being described.

Internationalisation: The character encoding used in the pathname will be whatever was originally passed to identify(). This might or might not be UTF-8, since it needs to be understood by the low-level C/C++ file I/O routines.

Returns: the pathname.

◆ str()

std::string regina::Output< FileInfo , false >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python str() and repr() functions.

Python: The Python "stringification" function str() will use precisely this function, and for most classes the Python repr() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ swap()

void regina::FileInfo::swap ( FileInfo & other )

inlinenoexcept

Swaps the contents of this and the given file information.

Parameters

other the object whose contents should be swapped with this.

◆ utf8()

std::string regina::Output< FileInfo , false >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeTextLong()

void regina::FileInfo::writeTextLong ( std::ostream & out ) const

Writes a detailed text representation of this object to the given output stream.

Python: Not present; use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

void regina::FileInfo::writeTextShort ( std::ostream & out ) const

Writes a short text representation of this object to the given output stream.

Python: Not present; use str() instead.

Parameters

out	the output stream to which to write.

The documentation for this class was generated from the following file:

file/fileinfo.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FileInfo() [1/2]

◆ FileInfo() [2/2]

Member Function Documentation

◆ detail()

◆ engine()

◆ format()

◆ formatDescription()

◆ identify()

◆ isCompressed()

◆ isInvalid()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ pathname()

◆ str()

◆ swap()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()