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.

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

long	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_int ()
	Reads an integer from the file.

void	write_int (index_t x, const char *comment=nullptr)
	Writes an 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 ()
	Reads an unsigned 64 bits integer from the file.

void	write_size (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_

long	current_chunk_size_

long	current_chunk_file_pos_

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

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 319 of file geofile.h.

◆ current_chunk_size()

long 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 327 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 472 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 486 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_int()

index_t GEO::GeoFile::read_int ( )

Reads an integer from 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.

Returns: the read integer

◆ read_size()

size_t GEO::GeoFile::read_size ( )

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 594 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_int()

void GEO::GeoFile::write_int	(	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 read. In Gargantua mode a 64-bits integer is read.

Parameters

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

◆ write_size()

void GEO::GeoFile::write_size ( 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 648 of file geofile.h.

◆ ascii_attribute_read_

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

staticprotected

Definition at line 656 of file geofile.h.

◆ ascii_attribute_write_

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

staticprotected

Definition at line 659 of file geofile.h.

◆ ascii_file_

FILE* GEO::GeoFile::ascii_file_

protected

Definition at line 649 of file geofile.h.

◆ attribute_sets_

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

protected

Definition at line 653 of file geofile.h.

◆ current_chunk_class_

std::string GEO::GeoFile::current_chunk_class_

protected

Definition at line 650 of file geofile.h.

◆ current_chunk_file_pos_

long GEO::GeoFile::current_chunk_file_pos_

protected

Definition at line 652 of file geofile.h.

◆ current_chunk_size_

long GEO::GeoFile::current_chunk_size_

protected

Definition at line 651 of file geofile.h.

◆ file_

gzFile GEO::GeoFile::file_

protected

Definition at line 647 of file geofile.h.

◆ filename_

std::string GEO::GeoFile::filename_

protected

Definition at line 646 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]

◆ is_ascii()

◆ read_chunk_class()

◆ read_int()

◆ read_size()

◆ read_string()

◆ read_string_array()

◆ register_ascii_attribute_serializer()

◆ string_array_size()

◆ string_size()

◆ write_chunk_class()

◆ write_chunk_header()

◆ write_int()

◆ write_size()

◆ write_string()

◆ write_string_array()

Member Data Documentation

◆ ascii_

◆ ascii_attribute_read_

◆ ascii_attribute_write_

◆ ascii_file_

◆ attribute_sets_

◆ current_chunk_class_

◆ current_chunk_file_pos_

◆ current_chunk_size_

◆ file_

◆ filename_