# Any kind of stream to read/write/both to or from a source
abstract class Stream
	# Codec used to transform raw data to text
	#
	# Note: defaults to UTF-8
	var codec: Codec = utf8_codec is protected writable(set_codec)

	# Lookahead buffer for codecs
	#
	# Since some codecs are multibyte, a lookahead may be required
	# to store the next bytes and consume them only if a valid character
	# is read.
	protected var lookahead: CString is noinit

	# Capacity of the lookahead
	protected var lookahead_capacity = 0

	# Current occupation of the lookahead
	protected var lookahead_length = 0

	# Buffer for writing data to a stream
	protected var write_buffer: CString is noinit

	init do
		var lcap = codec.max_lookahead
		lookahead = new CString(lcap)
		write_buffer = new CString(lcap)
		lookahead_length = 0
		lookahead_capacity = lcap
	end

	# Change the codec for this stream.
	fun codec=(c: Codec) do
		if c.max_lookahead > lookahead_capacity then
			var lcap = codec.max_lookahead
			var lk = new CString(lcap)
			var llen = lookahead_length
			if llen > 0 then
				lookahead.copy_to(lk, llen, 0, 0)
			end
			lookahead = lk
			lookahead_capacity = lcap
			write_buffer = new CString(lcap)
		end
		set_codec(c)
	end

	# Error produced by the file stream
	#
	#     var ifs = new FileReader.open("donotmakethisfile.binx")
	#     ifs.read_all
	#     ifs.close
	#     assert ifs.last_error != null
	var last_error: nullable IOError = null

	# close the stream
	fun close is abstract

	# Pre-work hook.
	#
	# Used to inform `self` that operations will start.
	# Specific streams can use this to prepare some resources.
	#
	# Is automatically invoked at the beginning of `with` structures.
	#
	# Do nothing by default.
	fun start do end

	# Post-work hook.
	#
	# Used to inform `self` that the operations are over.
	# Specific streams can use this to free some resources.
	#
	# Is automatically invoked at the end of `with` structures.
	#
	# call `close` by default.
	fun finish do close
end