|
| sdfio_status | sdfio_reader_create (const sdfio_allocator *allocator, sdfio_reader **reader) |
| | Creates a reader.
|
| sdfio_status | sdfio_reader_add_binary (sdfio_reader *reader) |
| | Adds the binary format to the formats that the reader reads, the version numbers bISO-1.0 and bISO-2.0.
|
| sdfio_status | sdfio_reader_add_ascii (sdfio_reader *reader) |
| | Adds the ASCII format to the formats that the reader reads, the version numbers aISO-1.0 and aISO-2.0.
|
| sdfio_status | sdfio_reader_set_buffer (sdfio_reader *reader, size_t size) |
| | Sets the size in bytes of the buffer between the reader and its stream.
|
| sdfio_status | sdfio_reader_set_chunk (sdfio_reader *reader, size_t count) |
| | Sets the number of values that the reader converts at a time.
|
| sdfio_status | sdfio_reader_set_time_zone (sdfio_reader *reader, const sdfio_time_zone *time_zone) |
| | Sets the conversion of the dates of ISO-1.0 files.
|
| size_t | sdfio_reader_magic_count (const sdfio_reader *reader) |
| | Returns the number of magics that a file can start with for the formats that the reader adds: two for each format, one for each revision.
|
| const char * | sdfio_reader_magic (const sdfio_reader *reader, size_t index) |
| | Returns a magic that a file can start with, for example "bISO-2.0": the letter b or a for the binary or the ASCII format, and the revision.
|
| sdfio_status | sdfio_reader_reset (sdfio_reader *reader) |
| | Returns a reader to the state new, so that it can open another file, block of memory or stream.
|
| void | sdfio_reader_free (sdfio_reader *reader) |
| | Releases a reader and closes the file that sdfio_open_file() opened, if any.
|
| sdfio_status | sdfio_open_memory (sdfio_reader *reader, const void *data, size_t size) |
| | Opens a block of memory as the source and reads the header.
|
| sdfio_status | sdfio_open_stream (sdfio_reader *reader, const sdfio_stream *stream) |
| | Opens a stream as the source and reads the header.
|
| const sdfio_header * | sdfio_reader_header (const sdfio_reader *reader) |
| | Returns the header of the opened file, or null if no file is open.
|
| sdfio_status | sdfio_read_data (sdfio_reader *reader, const sdfio_layout *layout, void *dst, size_t rows) |
| | Reads the next rows of the data area as the file codes them.
|
| sdfio_status | sdfio_read_heights (sdfio_reader *reader, const sdfio_layout *layout, void *dst) |
| | Reads the remaining rows as heights in metres into a buffer that lies in memory as the layout describes.
|
| sdfio_status | sdfio_read_trailer (sdfio_reader *reader, char *buffer, size_t capacity, size_t *size) |
| | Reads the next part of the trailer, the free text after the data area, into a buffer of the caller.
|
| const char * | sdfio_reader_error_message (const sdfio_reader *reader) |
| | Returns a description of the most recent failure of the reader, or an empty string if none occurred.
|
Reader of a file, memory or a stream.
- Process
- A reader reads one file at a time, from the start to the end:
- sdfio_reader_create() creates the reader.
- sdfio_reader_add_binary() and sdfio_reader_add_ascii() add the formats that it reads, at least one. sdfio_reader_set_buffer(), sdfio_reader_set_chunk() and sdfio_reader_set_time_zone() set the options.
- sdfio_open_file(), sdfio_open_memory() or sdfio_open_stream() opens the file and reads its header, which sdfio_reader_header() returns.
- sdfio_read_heights() reads the whole data area, or sdfio_read_data() reads it in parts of one row or more, in the order of the file.
- sdfio_read_trailer() reads the trailer, in parts, until it returns 0 bytes.
- sdfio_reader_free() releases the reader. sdfio_reader_reset() instead returns it to the state new, so that it can open another source.
- States
- A reader is in one of four states. It is new until a file is opened, then in the state data. The first call of sdfio_read_trailer() moves it to trailer, and the rows that were not read are discarded. An error that loses the position in the stream moves it to failed: SDFIO_ERR_IO, SDFIO_ERR_FORMAT, or SDFIO_ERR_RANGE in a call that reads. The header stays available in every state after the opening.
- Formats and options can be set in the state new only. The first attempt to open a file fixes them, also after sdfio_reader_reset().
- A call that the state does not allow returns SDFIO_ERR_STATE, and an invalid argument returns SDFIO_ERR_ARGUMENT. Neither changes the state or the position in the file.
- An opening that fails leaves the reader new, so it can open another file.
Reads the next rows of the data area as the file codes them.
dst receives rows times header->columns coded values of header->data_type in the byte order of the machine, in the order of the file. The bad value is not changed. ASCII values are parsed into the data type of the file, so that an ASCII file of float values is rounded to single precision. Use sdfio_decode_heights() to obtain heights in metres.
The buffer lies in memory as the layout describes, whose type has to be the data type of the file: the element (y, x) is stored at dst + y * layout.row_stride + x * layout.element_stride, where y counts the rows from the first row that is read. sdfio_layout_packed() describes values that follow each other. The bad value of the data type marks a point that is not measured.
The first row read is the first row stored in the file, the row with y = 0.
After an error the reader rejects further reads.
- Parameters
-
| [in,out] | reader | The reader. |
| [in] | layout | The layout of the buffer. |
| [out] | dst | The buffer for the coded values. |
| rows | The number of rows to read. |
- Return values
-
| SDFIO_ERR_ARGUMENT | A pointer is null, rows exceeds the rows remaining, the type of the layout is not the data type of the file, or the strides are invalid. |
| SDFIO_ERR_STATE | No file is open, or an earlier error ended the reading. |
| SDFIO_ERR_IO | The stream failed. |
| SDFIO_ERR_FORMAT | The data area is damaged or truncated. |
- Examples
- read_coded.c, and read_stream.c.
Reads the remaining rows as heights in metres into a buffer that lies in memory as the layout describes.
sdfio_layout_packed() describes a plain array.
The element (y, x) is stored at dst + y * layout.row_stride + x *
layout.element_stride. The row y = 0 is the first row. A negative row stride, with dst at the first element of the row y = 0, which is the last row in memory, stores the matrix upside down. A point that is not measured becomes NaN.
The function reads from the first row of the data area, so no rows may have been read before.
- Parameters
-
| [in,out] | reader | The reader. |
| [in] | layout | The layout of the buffer. |
| [out] | dst | The buffer for the heights. |
- Return values
-
| SDFIO_ERR_ARGUMENT | A pointer is null or the strides are invalid. |
| SDFIO_ERR_STATE | No file is open, an earlier error ended the reading, or rows were read already. |
| SDFIO_ERR_RANGE | A height does not fit the type of the buffer. |
| SDFIO_ERR_IO | The stream failed. |
| SDFIO_ERR_FORMAT | The data area is damaged or truncated. |
- Examples
- eigen.cpp, opencv.cpp, read_heights.c, and vtk.cpp.
Reads the next part of the trailer, the free text after the data area, into a buffer of the caller.
The call writes at most capacity bytes. A trailer that is longer than the buffer is read by calling the function again, and *size is 0 when the trailer is at its end, also for a file without one. The text is bytes, not terminated, and its encoding is not checked: the standard asks for 7-bit ASCII. Rows of the data area that have not been read are read and discarded by the first call.
Every line end of the text is LF, whether the file has CRLF or LF, in ASCII and in binary files. Nothing else of the text changes: the white space before it and the line ends at its end are part of it. In an ASCII file the trailer ends at the line that consists of *.
- Parameters
-
| [in,out] | reader | The reader. |
| [out] | buffer | Receives the text. |
| capacity | The size of buffer in bytes, at least 1. |
| [out] | size | Receives the number of bytes written, 0 at the end of the trailer. |
- Return values
-
| SDFIO_ERR_ARGUMENT | A pointer is null or the capacity is 0. |
| SDFIO_ERR_STATE | No file is open, or an earlier error ended the reading. |
| SDFIO_ERR_IO | The stream failed. |
| SDFIO_ERR_FORMAT | The file is damaged or truncated. |
- Examples
- read_heights.c.
Returns a reader to the state new, so that it can open another file, block of memory or stream.
A file that sdfio_open_file() opened is closed, and the header and the position in the data are dropped. The formats, the options and the buffers stay. The function works in every state, also after an error.
- Parameters
-
| [in,out] | reader | The reader. |
- Return values
-
| SDFIO_ERR_ARGUMENT | The reader is null. |
1.15.0