read_values
result = read_values(f, type, n)
Input: f, type, n · Output: result
What it is
Reads n (number, count) typed values from an already-open handle. f (file handle, opened readable, positioned wherever the caller left it) is the source. type (string, one of f64/f32/i64/u64/i32/u32/i16/u16/i8/u8/byte, with the aliases double, float, int64, uint64, int32, uint32, int16, uint16 for the first eight respectively) is the element type.
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = read_values(f, type, n) | f —f (file handle, opened readable, positioned wherever the caller left it) is the source.type stringtype (string, one of f64/f32/i64/u64/i32/u32/i16/u16/i8/u8/byte, with the aliases double, float, int64, uint64, int32, uint32, int16, uint16 for the first eight respectively) is the element type.n numberReads n (number, count) typed values from an already-open handle. | result Vec or number | Returns a Vec of up to n numbers (fewer if the file runs out first). Useful mid-stream, interleaved with other reads on the same handle; for a whole file in one call, use read_array instead. |
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("temps.bin", "wb")
write_double(f, 20.5)
write_double(f, 21.0)
write_double(f, 19.8)
close(f)
print(file_size("temps.bin")) # 24 -- 3 doubles, 8 bytes each
g = fopen("temps.bin", "rb")
vals = read_values(g, "f64", 3)
close(g)
print(vals) # [20.5, 21, 19.8]
whole = read_array("temps.bin", type="f64")
print(whole) # [20.5, 21, 19.8]
24 [20.5, 21, 19.8] [20.5, 21, 19.8]
from file-io
How it works
Typed binary reads: read_int16/read_uint16/read_int32/ read_uint32/read_float (32-bit)/read_double (64-bit), each with an endian= kwarg ("little" default, matching x86/most common convention, or "big"), via Rust's own from_le_bytes/from_be_bytes (no hand-rolled byte shuffling). Nothing if fewer bytes remain than the type needs — the same "exhausted" signal as every read above. read_values(f, type, n) -- n values of one type, from an open handle, in one call. The single-value reads above are the right shape for a header and the wrong one for a payload: a raw instrument capture is 100 000 float64 samples per channel, and reading it a value at a time is 100 000 builtin calls per file. That is not a slow way to read a measurement, it is a reason not to read one. read_array covers a whole file; this covers a RUN inside a file, which is what a record with a length prefix, an interleaved channel, or a header-then-payload layout actually needs. Short at EOF rather than an error, matching every other read here: the caller checks len.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.