Base class for reading or writing Geogram structured binary files. More...

#include <geogram/basic/geofile.h>

Inheritance diagram for GEO::GeoFile:

Classes
struct	AttributeInfo
	Internal representation of attributes. More...

struct	AttributeSetInfo
	Internal representation of an attribute set. More...

Public Types
typedef bool(*	AsciiAttributeSerializer) (FILE *file, Memory::pointer base_address, index_t nb_elements)
	The function pointer type for reading and writing attributes in ASCII files.

Public Member Functions
	GeoFile (const std::string &filename)
	GeoFile constructor.

	~GeoFile ()
	GeoFile destructor.

bool	is_ascii () const
	Tests whether this GeoFile is ascii.

bool	gargantua_mode () const
	Tests whether this GeoFile is in GARGANTUA mode.

const std::string &	current_chunk_class () const
	Gets the current chunk class.

size_t	current_chunk_size () const
	Gets the size of the current chunk.

AttributeSetInfo *	find_attribute_set (const std::string &name)
	Finds an attribute set by name.

const AttributeSetInfo *	find_attribute_set (const std::string &name) const
	Finds an attribute set by name.

index_t	read_index_t ()
	Reads an integer from the file.

void	write_index_t (index_t x, const char *comment=nullptr)
	Writes an integer into the file.

index_t	read_index_t_32 ()
	Reads a 32-bit integer from the file.

void	write_index_t_32 (index_t x, const char *comment=nullptr)
	Writes a 32-bit integer into the file.

std::string	read_string ()
	Reads a string from the file.

void	write_string (const std::string &s, const char *comment=nullptr)
	Writes a string into the file.

size_t	read_size_t ()
	Reads an unsigned 64 bits integer from the file.

void	write_size_t (size_t x)
	Writes an unsigned 64 bits integer into the file.

std::string	read_chunk_class ()
	Reads a chunk class from the file.

void	write_chunk_class (const std::string &chunk_class)
	Writes a chunk class into the file.

void	write_string_array (const std::vector< std::string > &strings)
	Writes a string array into the file.

void	read_string_array (std::vector< std::string > &strings)
	Reads a string array from the file.

size_t	string_size (const std::string &s) const
	Gets the size in bytes used by a given string in the file.

size_t	string_array_size (const std::vector< std::string > &strings) const
	Gets the size in bytes used by a given string array in the file.

void	read_chunk_header ()
	Reads a chunk header from the file.

void	write_chunk_header (const std::string &chunk_class, size_t size)
	Writes a chunk header into the file.

void	check_chunk_size ()
	Checks that the actual chunk size corresponds to the specified chunk size.

void	check_zlib_version ()
	Compares the zlib version declared in the header file with the zlib version obtained from the runtime, and outputs an error message if they differ.

void	clear_attribute_maps ()
	Clears all memorized information about attributes and attribute sets.

Static Public Member Functions
static void	register_ascii_attribute_serializer (const std::string &type_name, AsciiAttributeSerializer read, AsciiAttributeSerializer write)
	Declares a new attribute type that can be read from and written to ascii files.

Protected Attributes
std::string	filename_

gzFile	file_

bool	ascii_

FILE *	ascii_file_

std::string	current_chunk_class_

size_t	current_chunk_size_

size_t	current_chunk_file_pos_

std::map< std::string, AttributeSetInfo >	attribute_sets_

bool	gargantua_mode_
	True if current file is in GARGANTUA mode.

bool	convert_32_to_64_
	True if reading a standard file in GARGANTUA mode.

bool	convert_64_to_32_
	True if reading a GARGANTUA file in standard mode.

Static Protected Attributes
static std::map< std::string, AsciiAttributeSerializer >	ascii_attribute_read_

static std::map< std::string, AsciiAttributeSerializer >	ascii_attribute_write_

Detailed Description

Base class for reading or writing Geogram structured binary files.

Geogram structured binary files are organized into "chunks", in a way inspired by the Interchange File Format (IFF), with several differences (GeoFile uses little endian and does not use the standard IFF chunks). Like in IFF, each chunk starts with a four characters code (FourCC) and its size in bytes, stored in a 4 bytes unsigned integer. This makes it possible to easily skip the chunks that are not needed / not understood by the software. In addition, structured binary files are (optionally) compressed, using ZLib. Structured files can also be saved/loaded in ASCII, human-readable form. Natively, GeoFile uses the following chunks:

CMNT (Comment): contains a string
CMDL (Command Line): contains a vector of string
EOFL (End of file): an end of file marker. Can be used to indicate the boundaries of multiple objects stored in the same file
HEAD (Geofile header): contains the string GEOGRAM and a version string
PSET (Property Set): a set of properties. For instance, in a mesh, each mesh element type (vertices, edges, facets...) corresponds to a property set.
PROP (Property): a property attached to Property Set.
SPTR (Separator): marks the boundaries between multiple objects stored in the same GeoFile

Definition at line 269 of file geofile.h.

Member Typedef Documentation

◆ AsciiAttributeSerializer

typedef bool(* GEO::GeoFile::AsciiAttributeSerializer) (FILE *file, Memory::pointer base_address, index_t nb_elements)

The function pointer type for reading and writing attributes in ASCII files.

Definition at line 276 of file geofile.h.

Constructor & Destructor Documentation

◆ GeoFile()

GEO::GeoFile::GeoFile ( const std::string & filename )

GeoFile constructor.

Parameters

[in] filename a const reference to the file name.

Member Function Documentation

◆ clear_attribute_maps()

void GEO::GeoFile::clear_attribute_maps ( )

Clears all memorized information about attributes and attribute sets.

This function is called whenever a separator is read.

◆ current_chunk_class()

const std::string & GEO::GeoFile::current_chunk_class ( ) const

inline

Gets the current chunk class.

Returns: the current chunk class

Definition at line 333 of file geofile.h.

◆ current_chunk_size()

size_t GEO::GeoFile::current_chunk_size ( ) const

inline

Gets the size of the current chunk.

Returns: the size of the current chunk, in bytes

Definition at line 341 of file geofile.h.

◆ find_attribute_set() [1/2]

AttributeSetInfo * GEO::GeoFile::find_attribute_set ( const std::string & name )

inline

Finds an attribute set by name.

Parameters

[in] name a const reference to the name of the attribute set

Returns: a pointer to the AttributeSetInfo or nullptr if there is no such attribute set.

Definition at line 486 of file geofile.h.

◆ find_attribute_set() [2/2]

const AttributeSetInfo * GEO::GeoFile::find_attribute_set ( const std::string & name ) const

inline

Finds an attribute set by name.

Parameters

[in] name a const reference to the name of the attribute set

Returns: a const pointer to the AttributeSetInfo or nullptr if there is no such attribute set.

Definition at line 500 of file geofile.h.

◆ gargantua_mode()

bool GEO::GeoFile::gargantua_mode ( ) const

inline

Tests whether this GeoFile is in GARGANTUA mode.

In GARGANTUA mode, index_t is 64 bits wide, else it is 32 bits. geogram can be compiled in standard or GARGANTUA mode. When loading a GARGANTUA file in standard mode, each time an index_t is read, it is checked whether it fits in 32 bits. An exception is thrown if it is not the case.

Return values

true	if this file is in GARGANTUA mode
false	otherwise

Definition at line 325 of file geofile.h.

◆ is_ascii()

bool GEO::GeoFile::is_ascii ( ) const

inline

Tests whether this GeoFile is ascii.

GeoFile can be ascii or binary. If file name ends with "_ascii", then GeoFile is ascii.

Return values

true	if this GeoFile is ascii
false	otherwise

Definition at line 311 of file geofile.h.

◆ read_chunk_class()

std::string GEO::GeoFile::read_chunk_class ( )

Reads a chunk class from the file.

A chunk class is a 4 characters string. The function checks that I/O was completed and throws a GeoFileException if the file is truncated.

Returns: A 4 characters string with the chunk class.

◆ read_index_t()

index_t GEO::GeoFile::read_index_t ( )

Reads an integer from the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated. Reads 32 or 64 bits depending on whether geogram file is in GARGANTUA mode, and truncates or expands depending on current GARGANTUA mode. If file is in GARGANTUA mode and not current mode, check whether read integer fits in 32 bits and throws an exception if it is not the case.

Returns: the read integer

◆ read_index_t_32()

index_t GEO::GeoFile::read_index_t_32 ( )

Reads a 32-bit integer from the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated.

Returns: the read integer converted to index_t

◆ read_size_t()

size_t GEO::GeoFile::read_size_t ( )

Reads an unsigned 64 bits integer from the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated.

Returns: the read integer

◆ read_string()

std::string GEO::GeoFile::read_string ( )

Reads a string from the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated.

Returns: the read string

◆ read_string_array()

void GEO::GeoFile::read_string_array ( std::vector< std::string > & strings )

Reads a string array from the file.

Parameters

[out] strings the read string array, as a reference to a vector of strings.

◆ register_ascii_attribute_serializer()

static void GEO::GeoFile::register_ascii_attribute_serializer	(	const std::string &	type_name,
		AsciiAttributeSerializer	read,
		AsciiAttributeSerializer	write
	)

static

Declares a new attribute type that can be read from and written to ascii files.

Parameters

[in]	type_name	the C++ type name of the attribute
[in]	read	the function pointer for reading an attribute
[in]	write	the function pointer for writing an attribute

◆ string_array_size()

size_t GEO::GeoFile::string_array_size ( const std::vector< std::string > & strings ) const

Gets the size in bytes used by a given string array in the file.

Returns: the size in bytes used to store the string array in the file.

◆ string_size()

size_t GEO::GeoFile::string_size ( const std::string & s ) const

inline

Gets the size in bytes used by a given string in the file.

The file stored the length of the string in a 32 bits integer plus all the characters of the string

Returns: the size in bytes used to store the string in the file.

Definition at line 629 of file geofile.h.

◆ write_chunk_class()

void GEO::GeoFile::write_chunk_class ( const std::string & chunk_class )

Writes a chunk class into the file.

A chunk class is a 4 characters string. The function checks that I/O was completed and throws a GeoFileException if the file is truncated.

Parameters

[in] chunk_class A 4 characters string with the chunk class.

Precondition: chunk_class.length() == 4

◆ write_chunk_header()

void GEO::GeoFile::write_chunk_header	(	const std::string &	chunk_class,
		size_t	size
	)

Writes a chunk header into the file.

Parameters

[in]	chunk_class	the chunk class
[in]	size	the size in bytes of the data attached to the chunk.

When reading the file, to skip the chunk, one calls fseek(file_, size, SEEK_CUR)

◆ write_index_t()

void GEO::GeoFile::write_index_t	(	index_t	x,
		const char *	comment = `nullptr`
	)

Writes an integer into the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated. In Standard mode a 32-bits integer is written. In Gargantua mode a 64-bits integer is written.

Parameters

[in]	x	the integer
[in]	comment	an optional comment string, written to ASCII geofiles

◆ write_index_t_32()

void GEO::GeoFile::write_index_t_32	(	index_t	x,
		const char *	comment = `nullptr`
	)

Writes a 32-bit integer into the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated.

Parameters

[in]	x	the integer
[in]	comment	an optional comment string, written to ASCII geofiles

◆ write_size_t()

void GEO::GeoFile::write_size_t ( size_t x )

Writes an unsigned 64 bits integer into the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated.

Parameters

[in] x the integer

◆ write_string()

void GEO::GeoFile::write_string	(	const std::string &	s,
		const char *	comment = `nullptr`
	)

Writes a string into the file.

Checks that I/O was completed and throws a GeoFileException if the file is truncated.

Parameters

[in]	s	a const reference to the string
[in]	comment	an optional comment string, written to ASCII geofiles

◆ write_string_array()

void GEO::GeoFile::write_string_array ( const std::vector< std::string > & strings )

Writes a string array into the file.

Parameters

[in] strings the string array, as a const reference to a vector of strings.

Member Data Documentation

◆ ascii_

bool GEO::GeoFile::ascii_

protected

Definition at line 683 of file geofile.h.

◆ ascii_attribute_read_

std::map<std::string, AsciiAttributeSerializer> GEO::GeoFile::ascii_attribute_read_

staticprotected

Definition at line 691 of file geofile.h.

◆ ascii_attribute_write_

std::map<std::string, AsciiAttributeSerializer> GEO::GeoFile::ascii_attribute_write_

staticprotected

Definition at line 694 of file geofile.h.

◆ ascii_file_

FILE* GEO::GeoFile::ascii_file_

protected

Definition at line 684 of file geofile.h.

◆ attribute_sets_

std::map<std::string, AttributeSetInfo> GEO::GeoFile::attribute_sets_

protected

Definition at line 688 of file geofile.h.

◆ convert_32_to_64_

bool GEO::GeoFile::convert_32_to_64_

protected

True if reading a standard file in GARGANTUA mode.

Definition at line 703 of file geofile.h.

◆ convert_64_to_32_

bool GEO::GeoFile::convert_64_to_32_

protected

True if reading a GARGANTUA file in standard mode.

Definition at line 706 of file geofile.h.

◆ current_chunk_class_

std::string GEO::GeoFile::current_chunk_class_

protected

Definition at line 685 of file geofile.h.

◆ current_chunk_file_pos_

size_t GEO::GeoFile::current_chunk_file_pos_

protected

Definition at line 687 of file geofile.h.

◆ current_chunk_size_

size_t GEO::GeoFile::current_chunk_size_

protected

Definition at line 686 of file geofile.h.

◆ file_

gzFile GEO::GeoFile::file_

protected

Definition at line 682 of file geofile.h.

◆ filename_

std::string GEO::GeoFile::filename_

protected

Definition at line 681 of file geofile.h.

◆ gargantua_mode_

bool GEO::GeoFile::gargantua_mode_

protected

True if current file is in GARGANTUA mode.

In GARGANTUA mode, index_t has 64 bits

Definition at line 700 of file geofile.h.

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

geogram/basic/geofile.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ AsciiAttributeSerializer

Constructor & Destructor Documentation

◆ GeoFile()

Member Function Documentation

◆ clear_attribute_maps()

◆ current_chunk_class()

◆ current_chunk_size()

◆ find_attribute_set() [1/2]

◆ find_attribute_set() [2/2]

◆ gargantua_mode()

◆ is_ascii()

◆ read_chunk_class()

◆ read_index_t()

◆ read_index_t_32()

◆ read_size_t()

◆ read_string()

◆ read_string_array()

◆ register_ascii_attribute_serializer()

◆ string_array_size()

◆ string_size()

◆ write_chunk_class()

◆ write_chunk_header()

◆ write_index_t()

◆ write_index_t_32()

◆ write_size_t()

◆ write_string()

◆ write_string_array()

Member Data Documentation

◆ ascii_

◆ ascii_attribute_read_

◆ ascii_attribute_write_

◆ ascii_file_

◆ attribute_sets_

◆ convert_32_to_64_

◆ convert_64_to_32_

◆ current_chunk_class_

◆ current_chunk_file_pos_

◆ current_chunk_size_

◆ file_

◆ filename_

◆ gargantua_mode_