read_chars
result = read_chars(f, n)
Input: f, n · Output: result
What it is
Reads exactly n (number, count of Unicode characters, UTF-8 aware) characters from f (file handle, opened readable).
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = read_chars(f, n) | f numbernot documented yetn numbernot documented yet | result string | Returns a string of up to n characters — fewer than n if the file ends first — or Nothing if already at EOF. |
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("greeting.txt", "w")
write_char(f, "Hello,World")
close(f)
g = fopen("greeting.txt", "r")
first = read_char(g) # "H"
peeked = peek_char(g) # "e" -- cursor not moved
next = read_char(g) # "e" again, same char peeked returned
chunk = read_chars(g, 3) # "llo"
next_byte = peek_byte(g) # 44, the byte for ',' -- still not consumed
before_comma = read_until(g, ",") # "" -- the comma was right there, now consumed
w_byte = read_byte(g) # 87, the byte for 'W'
rest = read_all(g) # "orld"
close(g)
print("{first}{next}{chunk} peeked={peeked} next_byte={next_byte} before_comma=\"{before_comma}\" w_byte={w_byte} rest={rest}")
# Hello peeked=e next_byte=44 before_comma="" w_byte=87 rest=orld
Hello peeked=e next_byte=44 before_comma="" w_byte=87 rest=orld
from file-io
How it works
read_chars(f, n) — exactly n characters, UTF-8 aware (not a naive byte slice — decodes forward from the current byte position, same discipline as this session's string-utilities work). Returns fewer than n if the file ends first (like a plain read(n) in most languages), or Value::Nothing if already at EOF (zero available) — same "exhausted" signal as every other read here.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.