Status codes, enumerations, constants, and the structures for allocator, stream and time zone. More...

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

Data Structures
struct	sdfio_allocator
	Memory management callbacks that replace malloc() and free(), for example with a pool or a bump allocator. More...
struct	sdfio_stream
	Callbacks that provide or accept the bytes of a file. More...
struct	sdfio_date
	Calendar fields of a date and the time of day, with a resolution of one minute. More...
struct	sdfio_time_zone
	Conversion of the dates of ISO-1.0 files between the local clock of the writer and UTC. More...

Macros
#define	SDFIO_NO_TIME ((time_t)-1)
	Value of a date that is not recorded: a time_t of -1.
#define	SDFIO_AUTO_Z_SCALE 0.0
	Value of the z-scale of a header that requests the writer to select the z-scale.
#define	SDFIO_NO_RESOLUTION (-1.0)
	Value of the z-resolution of a header for an unknown resolution.
#define	SDFIO_MANUFACTURER_ID_MAX 10
	Length in bytes of the longest manufacturer's identifier, the size of its field in both formats.
#define	SDFIO_STREAM_ERROR ((size_t)-1)
	Return value of a read callback that failed: the largest size_t.

#define	SDFIO_BAD_INT8 INT8_MIN
	Bad value of each data type, the number that labels a point that is not measured or spurious: the minimum of an integer type, which the standard excludes for a valid height, and the lowest finite value of a floating-point type.
#define	SDFIO_BAD_INT16 INT16_MIN
	The bad value of SDFIO_TYPE_INT16.
#define	SDFIO_BAD_INT32 INT32_MIN
	The bad value of SDFIO_TYPE_INT32.
#define	SDFIO_BAD_FLOAT (-FLT_MAX)
	The bad value of SDFIO_TYPE_FLOAT, a float: -FLT_MAX.
#define	SDFIO_BAD_DOUBLE (-DBL_MAX)
	The bad value of SDFIO_TYPE_DOUBLE, a double: -DBL_MAX.

Typedefs
typedef enum sdfio_status	sdfio_status
	Result of a function call.
typedef enum sdfio_revision	sdfio_revision
	Revision of the SDF format that a file follows.
typedef enum sdfio_format	sdfio_format
	Format of a file.
typedef enum sdfio_data_type	sdfio_data_type
	Type of the coded values of the data area of a file, and of the elements of a buffer of heights.
typedef struct sdfio_allocator	sdfio_allocator
	Memory management callbacks that replace malloc() and free(), for example with a pool or a bump allocator.
typedef struct sdfio_stream	sdfio_stream
	Callbacks that provide or accept the bytes of a file.
typedef struct sdfio_date	sdfio_date
	Calendar fields of a date and the time of day, with a resolution of one minute.
typedef struct sdfio_time_zone	sdfio_time_zone
	Conversion of the dates of ISO-1.0 files between the local clock of the writer and UTC.

Enumerations
enum	sdfio_status { SDFIO_OK = 0 , SDFIO_ERR_ARGUMENT = 1 , SDFIO_ERR_STATE = 2 , SDFIO_ERR_IO = 3 , SDFIO_ERR_FORMAT = 4 , SDFIO_ERR_UNSUPPORTED = 5 , SDFIO_ERR_RANGE = 6 , SDFIO_ERR_BAD_VALUE = 7 , SDFIO_ERR_MEMORY = 8 }
	Result of a function call. More...
enum	sdfio_revision { SDFIO_ISO_1_0 = 0 , SDFIO_ISO_2_0 = 1 }
	Revision of the SDF format that a file follows. More...
enum	sdfio_format { SDFIO_BINARY = 0 , SDFIO_ASCII = 1 }
	Format of a file. More...
enum	sdfio_data_type { SDFIO_TYPE_FLOAT = 3 , SDFIO_TYPE_INT8 = 4 , SDFIO_TYPE_INT16 = 5 , SDFIO_TYPE_INT32 = 6 , SDFIO_TYPE_DOUBLE = 7 }
	Type of the coded values of the data area of a file, and of the elements of a buffer of heights. More...

Functions
const char *	sdfio_status_string (sdfio_status status)
	Returns a constant description of a status.
const sdfio_allocator *	sdfio_default_allocator (void)
	Returns the allocator that uses malloc() and free().
void	sdfio_stream_init (sdfio_stream *stream)
	Initializes a stream: every field is null, so the stream has no callback.
sdfio_status	sdfio_date_to_time (const sdfio_date date, time_t utc)
	Converts the fields of a date to a time, as if they were UTC.
sdfio_status	sdfio_date_from_time (time_t utc, sdfio_date *date)
	Converts a time to the fields of its UTC date.
void	sdfio_time_zone_init (sdfio_time_zone *time_zone)
	Initializes a time zone: every field is null, so it performs no conversion.
const sdfio_time_zone *	sdfio_system_time_zone (void)
	Returns the time zone of the machine, as its C library knows it.

Detailed Description

Status codes, enumerations, constants, and the structures for allocator, stream and time zone.

Macro Definition Documentation

◆ SDFIO_BAD_INT8

#define SDFIO_BAD_INT8 INT8_MIN

Bad value of each data type, the number that labels a point that is not measured or spurious: the minimum of an integer type, which the standard excludes for a valid height, and the lowest finite value of a floating-point type.

The bad value of SDFIO_TYPE_INT8.

◆ SDFIO_NO_RESOLUTION

#define SDFIO_NO_RESOLUTION (-1.0)

Value of the z-resolution of a header for an unknown resolution.

The standard represents it as a negative number, -1 by default. A reader reports it for every resolution that is not positive. A writer treats every value that is not positive as unknown and writes -1.

Typedef Documentation

◆ sdfio_allocator

typedef struct sdfio_allocator sdfio_allocator

Memory management callbacks that replace malloc() and free(), for example with a pool or a bump allocator.

A header calls them when it is created. A handle calls them for all of its memory, and only when it is created and when a file is created or opened. Reading and writing allocate nothing, so a pool can be sized in advance.

The structure is frozen for the major version: it has these three fields and a new property of an allocator is a new function.

◆ sdfio_data_type

typedef enum sdfio_data_type sdfio_data_type

Type of the coded values of the data area of a file, and of the elements of a buffer of heights.

Each enumerator is named after the C type of the values. The enumerator values are the data type codes of the standard, which calls SDFIO_TYPE_FLOAT "binary32" and SDFIO_TYPE_DOUBLE "binary64".

Enumerator	C type	Revisions	A buffer of heights
SDFIO_TYPE_FLOAT	float	ISO-2.0	yes
SDFIO_TYPE_DOUBLE	double	both	yes
SDFIO_TYPE_INT8	int8_t	ISO-2.0	no
SDFIO_TYPE_INT16	int16_t	both	no
SDFIO_TYPE_INT32	int32_t	both	no

A file of floating point values contains the heights in metres and has the z-scale 1. A file of integers contains the coded height information, which the z-scale multiplies to the heights in metres. sdfio_read_data() and sdfio_write_data() transfer the values as they are in the file, in the C type of the header's data type. sdfio_read_heights() and sdfio_write_heights() transfer heights, in a buffer of float or double.

◆ sdfio_date

typedef struct sdfio_date sdfio_date

Calendar fields of a date and the time of day, with a resolution of one minute.

The year is 1 to 9999, the month 1 to 12, the day 1 to the days of the month, the hour 0 to 23 and the minute 0 to 59. The fields of a file are in UTC for ISO-2.0 and are a clock reading in a zone that the file does not record for ISO-1.0.

The structure is frozen for the major version: it has these five fields and a new property of a date is a new function.

◆ sdfio_status

typedef enum sdfio_status sdfio_status

Result of a function call.

The values are part of the interface.

◆ sdfio_stream

typedef struct sdfio_stream sdfio_stream

Callbacks that provide or accept the bytes of a file.

A reader uses read. A writer uses write. The bytes are processed once and in order, as for a pipe. Without an initializer, call sdfio_stream_init() before assigning fields.

The structure is frozen for the major version: it has these three fields and a new property of a stream is a new function.

◆ sdfio_time_zone

typedef struct sdfio_time_zone sdfio_time_zone

Conversion of the dates of ISO-1.0 files between the local clock of the writer and UTC.

These files store a clock reading without a time zone. ISO-2.0 files store UTC and are not affected. A callback that is null performs no conversion, and the clock reading is used as if it were UTC.

On a system where the C library knows the zone, use sdfio_system_time_zone() and not an own conversion. Own callbacks are for a zone that the C library does not know, such as the fixed clock of a device.

The conversion of a reading that occurs twice, or not at all, when the clocks change is the decision of the callback. The result is correct only if the zone of the callbacks is the zone in which the file was written, which the file does not record. The callbacks are called by the thread that uses the handle. Without an initializer, call sdfio_time_zone_init() before assigning fields.

The structure is frozen for the major version: it has these three fields and a new property of a time zone is a new function.

Enumeration Type Documentation

◆ sdfio_data_type

enum sdfio_data_type

Type of the coded values of the data area of a file, and of the elements of a buffer of heights.

Each enumerator is named after the C type of the values. The enumerator values are the data type codes of the standard, which calls SDFIO_TYPE_FLOAT "binary32" and SDFIO_TYPE_DOUBLE "binary64".

Enumerator	C type	Revisions	A buffer of heights
SDFIO_TYPE_FLOAT	float	ISO-2.0	yes
SDFIO_TYPE_DOUBLE	double	both	yes
SDFIO_TYPE_INT8	int8_t	ISO-2.0	no
SDFIO_TYPE_INT16	int16_t	both	no
SDFIO_TYPE_INT32	int32_t	both	no

A file of floating point values contains the heights in metres and has the z-scale 1. A file of integers contains the coded height information, which the z-scale multiplies to the heights in metres. sdfio_read_data() and sdfio_write_data() transfer the values as they are in the file, in the C type of the header's data type. sdfio_read_heights() and sdfio_write_heights() transfer heights, in a buffer of float or double.

Enumerator
SDFIO_TYPE_FLOAT	float: IEEE 754 binary32.
SDFIO_TYPE_INT8	int8_t.
SDFIO_TYPE_INT16	int16_t.
SDFIO_TYPE_INT32	int32_t.
SDFIO_TYPE_DOUBLE	double: IEEE 754 binary64.

Examples: write_heights.c.

◆ sdfio_format

enum sdfio_format

Format of a file.

Enumerator
SDFIO_BINARY	Binary format.
SDFIO_ASCII	ASCII format.

◆ sdfio_revision

enum sdfio_revision

Revision of the SDF format that a file follows.

Enumerator
SDFIO_ISO_1_0	Revision ISO-1.0.
SDFIO_ISO_2_0	Revision ISO-2.0.

Examples: write_heights.c.

◆ sdfio_status

enum sdfio_status

Result of a function call.

The values are part of the interface.

Enumerator
SDFIO_OK	The call succeeded.
SDFIO_ERR_ARGUMENT	An argument is invalid, for example a null pointer or a row count that exceeds the rows remaining.
SDFIO_ERR_STATE	The call is not valid in the current state of the handle, for example opening a reader a second time.
SDFIO_ERR_IO	The stream failed, or a file could not be opened.
SDFIO_ERR_FORMAT	The data is not an SDF file, is damaged or is truncated.
SDFIO_ERR_UNSUPPORTED	The file needs a format that has not been added to the handle.
SDFIO_ERR_RANGE	A number does not fit the type that has to store it.
SDFIO_ERR_BAD_VALUE	A height equals the bad value of the data type, so it would be read as a point that is not measured.
SDFIO_ERR_MEMORY	An allocation failed.

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_date_from_time()

sdfio_status sdfio_date_from_time	(	time_t	utc,
		sdfio_date *	date )

Converts a time to the fields of its UTC date.

The function replaces gmtime_r(), and the seconds are dropped, so the result is the minute at or before the time.

Parameters

	utc	The time.
[out]	date	Receives the fields.

Return values

SDFIO_ERR_ARGUMENT	date is null.
SDFIO_ERR_RANGE	The year of the time is not 1 to 9999.

Examples: custom_timezone.c.

◆ sdfio_date_to_time()

sdfio_status sdfio_date_to_time	(	const sdfio_date *	date,
		time_t *	utc )

Converts the fields of a date to a time, as if they were UTC.

The function replaces timegm(), which is not part of the C standard, and uses no function of the C library that has a time zone or a shared result.

Parameters

[in]	date	The fields.
[out]	utc	Receives the time, with the seconds 0.

Return values

SDFIO_ERR_ARGUMENT	A pointer is null, or a field is out of its range.
SDFIO_ERR_RANGE	The time does not fit a time_t.

Examples: custom_timezone.c.

◆ sdfio_default_allocator()

const sdfio_allocator * sdfio_default_allocator ( void )

Returns the allocator that uses malloc() and free().

Returns: A pointer to a constant allocator, valid for the life of the program.

Examples: 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.

◆ sdfio_status_string()

const char * sdfio_status_string ( sdfio_status status )

Returns a constant description of a status.

The result is never null.

Parameters

status The status to describe.

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

◆ sdfio_stream_init()

void sdfio_stream_init ( sdfio_stream * stream )

Initializes a stream: every field is null, so the stream has no callback.

The caller sets user and the callback that its handle uses.

Parameters

[out] stream The stream to initialize.

◆ sdfio_system_time_zone()

const sdfio_time_zone * sdfio_system_time_zone ( void )

Returns the time zone of the machine, as its C library knows it.

The conversion uses mktime() and localtime_r(), or localtime_s() on Windows, so a reading that occurs twice or not at all is resolved as mktime() resolves it. The zone is the one of the process: changing it while threads convert dates is a data race.

Returns: A pointer to a constant time zone, valid for the life of the program.

Examples: write_heights.c.

◆ sdfio_time_zone_init()

void sdfio_time_zone_init ( sdfio_time_zone * time_zone )

Initializes a time zone: every field is null, so it performs no conversion.

The caller sets user and the callbacks.

Parameters

[out] time_zone The time zone to initialize.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SDFIO_BAD_INT8

◆ SDFIO_NO_RESOLUTION

Typedef Documentation

◆ sdfio_allocator

◆ sdfio_data_type

◆ sdfio_date

◆ sdfio_status

◆ sdfio_stream

◆ sdfio_time_zone

Enumeration Type Documentation

◆ sdfio_data_type

◆ sdfio_format

◆ sdfio_revision

◆ sdfio_status

Function Documentation

◆ sdfio_date_from_time()

◆ sdfio_date_to_time()

◆ sdfio_default_allocator()

◆ sdfio_status_string()

◆ sdfio_stream_init()

◆ sdfio_system_time_zone()

◆ sdfio_time_zone_init()