read_struct
result = read_struct(f, fields)
Input: f, fields · Output: result
What it is
Reads one fixed-width binary record from f (file handle, opened readable). fields (list of [name, type] pairs, e.g. [["t", "f64"], ["ch", "u16"]]) describes the record's layout in byte order, using the same type names as read_values.
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = read_struct(f, fields) | f —Reads one fixed-width binary record from f (file handle, opened readable).fields —fields (list of [name, type] pairs, e.g. | result — | Returns a record with one field per entry in fields, or Nothing if fewer bytes remain than a full record needs. |
Examples
From the documentation, and run by the build -- the output and the figure below are what the engine actually produced. Simplest first.
f = fopen("records.bin", "wb")
write_double(f, 0.0)
write_uint16(f, 12)
write_double(f, 0.5)
write_uint16(f, 15)
close(f)
fields = [["t", "f64"], ["ch", "u16"]]
g = fopen("records.bin", "rb")
one = read_struct(g, fields)
close(g)
print(one.t) # 0
print(one.ch) # 12
h = fopen("records.bin", "rb")
tbl = read_structs(h, fields, 2)
close(h)
print(nrow(tbl)) # 2
print(tbl.ch) # [12, 15]
0 12 2 [12, 15]
from file-io
How it works
read_struct(f, fields) / read_structs(f, fields, n) -- one binary record, or n of them. fields is a list of (name, type) pairs, which is the layout written down: (("t", "f64"), ("ch", "u16")) reads a ten-byte record and hands back {t = ..., ch = ...}. A file of fixed-size records is the commonest binary format there is -- logger output, a scope's native save, anything with a header struct -- and Qu could only read one by counting bytes by hand. read_structs returns a TABLE, one column per field, rather than a list of records: the reason to read a thousand records is to work on the columns.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.