Header of a file: size, scales, data type, dates and manufacturer. More...

#include <sdfio/sdfio_export.h>
#include <sdfio/types.h>
#include <stdbool.h>
#include <stdint.h>
#include <time.h>

Typedefs
typedef struct sdfio_header	sdfio_header
	Header of a file, with the field names of the standard.

Functions
sdfio_status	sdfio_header_create (const sdfio_allocator allocator, sdfio_header *header)
	Creates a header with default values.
sdfio_status	sdfio_header_copy (sdfio_header dst, const sdfio_header src)
	Copies every field of a header into another header, which keeps its allocator.
void	sdfio_header_free (sdfio_header *header)
	Releases a header that sdfio_header_create() created.
sdfio_revision	sdfio_header_revision (const sdfio_header *header)
	Returns the revision of the format.
sdfio_status	sdfio_header_set_revision (sdfio_header *header, sdfio_revision revision)
	Sets the revision of the format.
sdfio_format	sdfio_header_format (const sdfio_header *header)
	Returns the format of the file.
sdfio_status	sdfio_header_set_format (sdfio_header *header, sdfio_format format)
	Sets the format of the file.
sdfio_data_type	sdfio_header_data_type (const sdfio_header *header)
	Returns the data type of the coded values in the data area.
sdfio_status	sdfio_header_set_data_type (sdfio_header *header, sdfio_data_type data_type)
	Sets the data type of the coded values in the data area.
uint32_t	sdfio_header_columns (const sdfio_header *header)
	Returns the number of columns M of the data matrix: the points along x.
sdfio_status	sdfio_header_set_columns (sdfio_header *header, uint32_t columns)
	Sets the number of columns M of the data matrix.
uint32_t	sdfio_header_rows (const sdfio_header *header)
	Returns the number of rows N of the data matrix: 1 for a profile.
sdfio_status	sdfio_header_set_rows (sdfio_header *header, uint32_t rows)
	Sets the number of rows N of the data matrix.
double	sdfio_header_x_scale (const sdfio_header *header)
	Returns the sampling interval along x in metres (X-scale factor).
sdfio_status	sdfio_header_set_x_scale (sdfio_header *header, double x_scale)
	Sets the sampling interval along x in metres.
double	sdfio_header_y_scale (const sdfio_header *header)
	Returns the sampling interval along y in metres (Y-scale factor).
sdfio_status	sdfio_header_set_y_scale (sdfio_header *header, double y_scale)
	Sets the sampling interval along y in metres.
double	sdfio_header_z_scale (const sdfio_header *header)
	Returns the z-scale factor: the height in metres that a coded value of 1 in the data area stands for.
sdfio_status	sdfio_header_set_z_scale (sdfio_header *header, double z_scale)
	Sets the z-scale factor.
double	sdfio_header_z_resolution (const sdfio_header *header)
	Returns the z-resolution: the quantization step of the instrument in metres, or SDFIO_NO_RESOLUTION.
sdfio_status	sdfio_header_set_z_resolution (sdfio_header *header, double z_resolution)
	Sets the z-resolution.
time_t	sdfio_header_created (const sdfio_header *header)
	Returns the original creation date and time as a time_t, which is read as integer seconds since 1970-01-01 00:00:00 UTC, as POSIX defines it, with a resolution of one minute.
sdfio_status	sdfio_header_set_created (sdfio_header *header, time_t created)
	Sets the original creation date and time, rounded down to the minute.
time_t	sdfio_header_modified (const sdfio_header *header)
	Returns the last modification date and time.
sdfio_status	sdfio_header_set_modified (sdfio_header *header, time_t modified)
	Sets the last modification date and time.
sdfio_status	sdfio_header_set_dates (sdfio_header *header, time_t date)
	Sets the creation date and the modification date to the same time, rounded down to the minute.
const char *	sdfio_header_manufacturer (const sdfio_header *header)
	Returns the manufacturer's identifier: at most SDFIO_MANUFACTURER_ID_MAX bytes, terminated by a null character.
sdfio_status	sdfio_header_set_manufacturer (sdfio_header header, const char manufacturer)
	Sets the manufacturer's identifier.
bool	sdfio_revision_allows (sdfio_revision revision, sdfio_data_type type)
	Returns true if a revision permits a data type.

Detailed Description

Header of a file: size, scales, data type, dates and manufacturer.

Typedef Documentation

◆ sdfio_header

typedef struct sdfio_header sdfio_header

Header of a file, with the field names of the standard.

The points of the matrix lie in a right-handed coordinate system: x grows with the column, y with the row, and z points to the viewer who looks from above. The row y = 0 is the first row of the file.

A writer keeps a copy of the header it takes. The compression type and the checksum type are not members: the standard allows neither.

Setters check what depends on their field alone. sdfio_create_file() and sdfio_create_stream() check the rest: the data type against the revision, the numbers of columns and rows against the limit of the revision, and the dates.

Examples: custom_allocator.c, custom_timezone.c, eigen.cpp, opencv.cpp, read_coded.c, read_heights.c, read_stream.c, vtk.cpp, write_coded.c, write_heights.c, and write_memory.c.

Function Documentation

◆ sdfio_header_columns()

uint32_t sdfio_header_columns ( const sdfio_header * header )

Returns the number of columns M of the data matrix: the points along x.

Parameters

[in] header The header.

Examples: custom_allocator.c, eigen.cpp, opencv.cpp, read_coded.c, read_heights.c, read_stream.c, and vtk.cpp.

◆ sdfio_header_copy()

sdfio_status sdfio_header_copy	(	sdfio_header *	dst,
		const sdfio_header *	src )

Copies every field of a header into another header, which keeps its allocator.

A copy of the header of a reader is a header that the caller can change and keep after the reader is freed.

Parameters

[out]	dst	The header that receives the fields.
[in]	src	The header to copy.

Return values

SDFIO_ERR_ARGUMENT A pointer is null.

Examples: eigen.cpp, and opencv.cpp.

◆ sdfio_header_create()

sdfio_status sdfio_header_create	(	const sdfio_allocator *	allocator,
		sdfio_header **	header )

Creates a header with default values.

The defaults are: revision ISO-2.0, binary format, data type SDFIO_TYPE_FLOAT, x_scale and y_scale of 1, z_scale SDFIO_AUTO_Z_SCALE, z_resolution SDFIO_NO_RESOLUTION, both dates SDFIO_NO_TIME, manufacturer "libsdfio", and zero columns and rows. The caller sets the number of columns and rows, the dates, which a file that is written requires, and every other field that differs. The function does not read the clock, so a system without one needs none.

Parameters

[in]	allocator	The allocator of the header, for example sdfio_default_allocator(). The structure is copied, so it need not outlive the call. Both callbacks must be set.
[out]	header	Receives the header, or null if the call fails. The caller releases it with sdfio_header_free().

Return values

SDFIO_ERR_ARGUMENT	A pointer is null, or the allocator lacks a callback.
SDFIO_ERR_MEMORY	The allocation failed.

Examples: custom_timezone.c, eigen.cpp, opencv.cpp, write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_created()

time_t sdfio_header_created ( const sdfio_header * header )

Returns the original creation date and time as a time_t, which is read as integer seconds since 1970-01-01 00:00:00 UTC, as POSIX defines it, with a resolution of one minute.

A file that is read can have none (SDFIO_NO_TIME). ISO-2.0 files store UTC. ISO-1.0 files store the local clock of the writer, without a time zone. The reader converts it with the sdfio_time_zone of the reader, and without one the header stores the clock reading as UTC.

Parameters

[in] header The header.

Examples: custom_timezone.c.

◆ sdfio_header_data_type()

sdfio_data_type sdfio_header_data_type ( const sdfio_header * header )

Returns the data type of the coded values in the data area.

Parameters

[in] header The header.

Examples: read_coded.c, and read_stream.c.

◆ sdfio_header_format()

sdfio_format sdfio_header_format ( const sdfio_header * header )

Returns the format of the file.

Parameters

[in] header The header.

◆ sdfio_header_free()

void sdfio_header_free ( sdfio_header * header )

Releases a header that sdfio_header_create() created.

A null pointer is ignored. The header that sdfio_reader_header() returns is not released.

Parameters

[in] header The header.

Examples: custom_timezone.c, eigen.cpp, opencv.cpp, write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_manufacturer()

const char * sdfio_header_manufacturer ( const sdfio_header * header )

Returns the manufacturer's identifier: at most SDFIO_MANUFACTURER_ID_MAX bytes, terminated by a null character.

The standard asks for 7-bit ASCII, and the bytes of a file are returned as they are. The pointer is valid until the header is modified or freed.

Parameters

[in] header The header.

◆ sdfio_header_modified()

time_t sdfio_header_modified ( const sdfio_header * header )

Returns the last modification date and time.

The rules of the creation date apply.

Parameters

[in] header The header.

◆ sdfio_header_revision()

sdfio_revision sdfio_header_revision ( const sdfio_header * header )

Returns the revision of the format.

Parameters

[in] header The header.

Examples: read_coded.c, and read_heights.c.

◆ sdfio_header_rows()

uint32_t sdfio_header_rows ( const sdfio_header * header )

Returns the number of rows N of the data matrix: 1 for a profile.

Parameters

[in] header The header.

Examples: custom_allocator.c, eigen.cpp, opencv.cpp, read_coded.c, read_heights.c, read_stream.c, and vtk.cpp.

◆ sdfio_header_set_columns()

sdfio_status sdfio_header_set_columns	(	sdfio_header *	header,
		uint32_t	columns )

Sets the number of columns M of the data matrix.

ISO-1.0 stores 16 bits, so the limit of the revision is checked when the file is created.

Parameters

[in,out]	header	The header.
	columns	The number of columns.

Return values

SDFIO_ERR_ARGUMENT header is null.

Examples: custom_timezone.c, write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_created()

sdfio_status sdfio_header_set_created	(	sdfio_header *	header,
		time_t	created )

Sets the original creation date and time, rounded down to the minute.

A file that is written requires one, so sdfio_create_file() and sdfio_create_stream() reject SDFIO_NO_TIME.

Parameters

[in,out]	header	The header.
	created	The date, or SDFIO_NO_TIME.

Return values

SDFIO_ERR_ARGUMENT header is null, or the year is out of the range of the SDF files.

Examples: custom_timezone.c.

◆ sdfio_header_set_data_type()

sdfio_status sdfio_header_set_data_type	(	sdfio_header *	header,
		sdfio_data_type	data_type )

Sets the data type of the coded values in the data area.

Parameters

[in,out]	header	The header.
	data_type	The data type.

Return values

SDFIO_ERR_ARGUMENT A pointer is null, or the value is not an enumerator.

Examples: custom_timezone.c, eigen.cpp, opencv.cpp, write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_dates()

sdfio_status sdfio_header_set_dates	(	sdfio_header *	header,
		time_t	date )

Sets the creation date and the modification date to the same time, rounded down to the minute.

Neither date changes if the call fails.

Parameters

[in,out]	header	The header.
	date	The date, or SDFIO_NO_TIME.

Return values

SDFIO_ERR_ARGUMENT header is null, or the year is out of the range of the SDF files.

Examples: write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_format()

sdfio_status sdfio_header_set_format	(	sdfio_header *	header,
		sdfio_format	format )

Sets the format of the file.

Parameters

[in,out]	header	The header.
	format	The format.

Return values

SDFIO_ERR_ARGUMENT A pointer is null, or the value is not an enumerator.

Examples: eigen.cpp, and opencv.cpp.

◆ sdfio_header_set_manufacturer()

sdfio_status sdfio_header_set_manufacturer	(	sdfio_header *	header,
		const char *	manufacturer )

Sets the manufacturer's identifier.

An identifier of more than SDFIO_MANUFACTURER_ID_MAX bytes is cut to that length.

Parameters

[in,out]	header	The header.
[in]	manufacturer	The identifier, terminated by a null character.

Return values

SDFIO_ERR_ARGUMENT A pointer is null, or the identifier contains a CR or an LF within the first SDFIO_MANUFACTURER_ID_MAX bytes. The encoding is not checked; the standard asks for 7-bit ASCII.

◆ sdfio_header_set_modified()

sdfio_status sdfio_header_set_modified	(	sdfio_header *	header,
		time_t	modified )

Sets the last modification date and time.

The rules of the creation date apply, except that a file is written with the creation date if the modification date is SDFIO_NO_TIME.

Parameters

[in,out]	header	The header.
	modified	The date, or SDFIO_NO_TIME.

Return values

SDFIO_ERR_ARGUMENT header is null, or the year is out of the range of the SDF files.

Examples: custom_timezone.c.

◆ sdfio_header_set_revision()

sdfio_status sdfio_header_set_revision	(	sdfio_header *	header,
		sdfio_revision	revision )

Sets the revision of the format.

Parameters

[in,out]	header	The header.
	revision	The revision.

Return values

SDFIO_ERR_ARGUMENT A pointer is null, or the value is not an enumerator.

Examples: custom_timezone.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_rows()

sdfio_status sdfio_header_set_rows	(	sdfio_header *	header,
		uint32_t	rows )

Sets the number of rows N of the data matrix.

ISO-1.0 stores 16 bits, so the limit of the revision is checked when the file is created.

Parameters

[in,out]	header	The header.
	rows	The number of rows.

Return values

SDFIO_ERR_ARGUMENT header is null.

Examples: custom_timezone.c, write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_x_scale()

sdfio_status sdfio_header_set_x_scale	(	sdfio_header *	header,
		double	x_scale )

Sets the sampling interval along x in metres.

Parameters

[in,out]	header	The header.
	x_scale	The interval, a finite number.

Return values

SDFIO_ERR_ARGUMENT header is null, or the value is not finite.

Examples: write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_y_scale()

sdfio_status sdfio_header_set_y_scale	(	sdfio_header *	header,
		double	y_scale )

Sets the sampling interval along y in metres.

Any finite value is written for a profile.

Parameters

[in,out]	header	The header.
	y_scale	The interval, a finite number.

Return values

SDFIO_ERR_ARGUMENT header is null, or the value is not finite.

Examples: write_coded.c, write_heights.c, and write_memory.c.

◆ sdfio_header_set_z_resolution()

sdfio_status sdfio_header_set_z_resolution	(	sdfio_header *	header,
		double	z_resolution )

Sets the z-resolution.

Parameters

[in,out]	header	The header.
	z_resolution	A finite number. A number that is not positive means SDFIO_NO_RESOLUTION.

Return values

SDFIO_ERR_ARGUMENT header is null, or the value is not finite.

Examples: write_coded.c.

◆ sdfio_header_set_z_scale()

sdfio_status sdfio_header_set_z_scale	(	sdfio_header *	header,
		double	z_scale )

Sets the z-scale factor.

A writer treats SDFIO_AUTO_Z_SCALE as 1 for the floating point data types. For the integer data types, sdfio_write_heights() selects the z-scale from the heights, whereas sdfio_write_data() requires it to be set.

Parameters

[in,out]	header	The header.
	z_scale	A positive finite number, or SDFIO_AUTO_Z_SCALE.

Return values

SDFIO_ERR_ARGUMENT header is null, or the value is neither.

Examples: write_coded.c.

◆ sdfio_header_x_scale()

double sdfio_header_x_scale ( const sdfio_header * header )

Returns the sampling interval along x in metres (X-scale factor).

Parameters

[in] header The header.

Examples: vtk.cpp.

◆ sdfio_header_y_scale()

double sdfio_header_y_scale ( const sdfio_header * header )

Returns the sampling interval along y in metres (Y-scale factor).

It is meaningless for a profile.

Parameters

[in] header The header.

Examples: vtk.cpp.

◆ sdfio_header_z_resolution()

double sdfio_header_z_resolution ( const sdfio_header * header )

Returns the z-resolution: the quantization step of the instrument in metres, or SDFIO_NO_RESOLUTION.

It is independent of the z-scale, because data can be rescaled after the measurement.

Parameters

[in] header The header.

◆ sdfio_header_z_scale()

double sdfio_header_z_scale ( const sdfio_header * header )

Returns the z-scale factor: the height in metres that a coded value of 1 in the data area stands for.

A reader always sets it.

Parameters

[in] header The header.

Examples: read_coded.c.

◆ sdfio_revision_allows()

bool sdfio_revision_allows	(	sdfio_revision	revision,
		sdfio_data_type	type )

Returns true if a revision permits a data type.

Parameters

revision	The revision.
type	The data type.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ sdfio_header

Function Documentation

◆ sdfio_header_columns()

◆ sdfio_header_copy()

◆ sdfio_header_create()

◆ sdfio_header_created()

◆ sdfio_header_data_type()

◆ sdfio_header_format()

◆ sdfio_header_free()

◆ sdfio_header_manufacturer()

◆ sdfio_header_modified()

◆ sdfio_header_revision()

◆ sdfio_header_rows()

◆ sdfio_header_set_columns()

◆ sdfio_header_set_created()

◆ sdfio_header_set_data_type()

◆ sdfio_header_set_dates()

◆ sdfio_header_set_format()

◆ sdfio_header_set_manufacturer()

◆ sdfio_header_set_modified()

◆ sdfio_header_set_revision()

◆ sdfio_header_set_rows()

◆ sdfio_header_set_x_scale()

◆ sdfio_header_set_y_scale()

◆ sdfio_header_set_z_resolution()

◆ sdfio_header_set_z_scale()

◆ sdfio_header_x_scale()

◆ sdfio_header_y_scale()

◆ sdfio_header_z_resolution()

◆ sdfio_header_z_scale()

◆ sdfio_revision_allows()