read_structs
result = read_structs(f, fields, n)
Input: f, fields, n · Output: result
What it is
Reads up to n (number) fixed-width binary records from f (file handle, opened readable), using the same fields layout read_struct takes.
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = read_structs(f, fields, n) | f numbernot documented yetfields numbernot documented yetn numbernot documented yet | result Table | Returns a Table with one column per field (not one row-record per call) — the more useful shape once there are enough records to work on column-wise, stopping early (with however many complete records were read) if the file runs out. |
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.