set_stream_position(s, pos, @optional whence = 'beginning)

A stream may allow its current position to be moved directly to a different position in the underlying stream of bytes or characters. If so, set_stream_position changes the current position to pos. For binary streams, pos must be an exact nonnegative integer byte displacement from the start of the byte stream. For textual streams, the representation of a position is unspecified, but pos must be an appropriate position for the textual stream. If set_stream_position is called on a stream that does not support it, an exception is raised.

The symbolic argument whence should be one of: 'beginning, 'current or 'end. When whence is omitted or is 'beginning, the position is relative to the beginning of the file. When whence is 'current, pos is taken to be relative to the current byte position of the file. When whence is 'end, pos is taken to be relative to the end of the file.

If the stream s is a binary output stream and the position is set beyond the current end of the data in the underlying stream, s is not extended until new data is written at that position. If new data is written at that position, the contents of each intervening position is unspecified. Binary streams created with file_writer and file_reader can always be extended in this manner within the limits of the underlying operating system. In other cases, attempts to set the stream beyond the current end of data in the underlying object may result in an exception.

Return the new position on success.


let s = file_stream("out.txt", options = ['create])
showln(stream = s, "hello, world")
set_stream_position(s, 0)
// hello, world

Also see:


Core Module Index | Contents