Geogram  Version 1.9.1
A programming library of geometric algorithms
GEO::GeoFile Class Reference

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

#include <geogram/basic/geofile.h>

Inheritance diagram for GEO::GeoFile:
GEO::InputGeoFile GEO::OutputGeoFile

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. More...
 
 ~GeoFile ()
 GeoFile destructor.
 
bool is_ascii () const
 Tests whether this GeoFile is ascii. More...
 
const std::string & current_chunk_class () const
 Gets the current chunk class. More...
 
long current_chunk_size () const
 Gets the size of the current chunk. More...
 
AttributeSetInfofind_attribute_set (const std::string &name)
 Finds an attribute set by name. More...
 
const AttributeSetInfofind_attribute_set (const std::string &name) const
 Finds an attribute set by name. More...
 
index_t read_int ()
 Reads an integer from the file. More...
 
void write_int (index_t x, const char *comment=nullptr)
 Writes an integer into the file. More...
 
std::string read_string ()
 Reads a string from the file. More...
 
void write_string (const std::string &s, const char *comment=nullptr)
 Writes a string into the file. More...
 
size_t read_size ()
 Reads an unsigned 64 bits integer from the file. More...
 
void write_size (size_t x)
 Writes an unsigned 64 bits integer into the file. More...
 
std::string read_chunk_class ()
 Reads a chunk class from the file. More...
 
void write_chunk_class (const std::string &chunk_class)
 Writes a chunk class into the file. More...
 
void write_string_array (const std::vector< std::string > &strings)
 Writes a string array into the file. More...
 
void read_string_array (std::vector< std::string > &strings)
 Reads a string array from the file. More...
 
size_t string_size (const std::string &s) const
 Gets the size in bytes used by a given string in the file. More...
 
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. More...
 
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. More...
 
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. More...
 

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. More...
 

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, AttributeSetInfoattribute_sets_
 

Static Protected Attributes

static std::map< std::string, AsciiAttributeSerializerascii_attribute_read_
 
static std::map< std::string, AsciiAttributeSerializerascii_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.

Constructor & Destructor Documentation

◆ GeoFile()

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

GeoFile constructor.

Parameters
[in]filenamea 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]namea 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]namea 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
trueif this GeoFile is ascii
falseotherwise

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]stringsthe 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_namethe C++ type name of the attribute
[in]readthe function pointer for reading an attribute
[in]writethe 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_classA 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_classthe chunk class
[in]sizethe 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]xthe integer
[in]commentan 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]xthe 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]sa const reference to the string
[in]commentan 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]stringsthe string array, as a const reference to a vector of strings.

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