4.4 Counting Positions, Lines, and Columns🔗ℹ

By default, Rhombus keeps track of the position in a port as the number of bytes that have been read from or written to the port (independent of the read/write position, which is accessed or changed with Port.Position). Optionally, however, Rhombus can track the position in terms of characters (after UTF-8 decoding), instead of bytes, and it can track line locations and column locations; this optional tracking must be specifically enabled for a port via Port.locations_enabled or the Port.current_enable_locations parameter. Position, line, and column locations for a port are used by various reading and parsing operations, such as shrubbery.read. Position and line locations are numbered from 1; column locations are numbered from 0.

When counting lines, Rhombus treats linefeed, return, and return-linefeed combinations as a line terminator and as a single position (on all platforms). Each tab advances the column count to one before the next multiple of 8. When a sequence of bytes in the range 128 to 253 forms a UTF-8 encoding of a character, the position/column is incremented once for each byte, and then decremented appropriately when a complete encoding sequence is discovered. See also Encodings and Locales for more information on UTF-8 decoding for ports.

A position is known for any port as long as its value can be expressed as a Fixnum (which is more than enough tracking for realistic applications in, say, syntax-error reporting). If the position for a port exceeds the value of the largest Fixnum, then the position for the port becomes unknown, and line and column tacking is disabled. Return-linefeed combinations are treated as a single character position only when line and column counting is enabled.