package core:io

⌘K
Ctrl+K
or
/

    Overview

    Basic interfaces for generic data stream primitives. The purpose of this package is wrap existing data structures and their operations into an abstracted stream interface.

    Index

    Constants (0)

    This section is empty.

    Variables (0)

    This section is empty.

    Procedures (73)
    Procedure Groups (0)

    This section is empty.

    Types

    Counting_Stream ¶

    Counting_Stream :: struct {
    	s:             Stream,
    	// underlying stream, or nil to discard writes
    	bytes_read:    i64,
    	// by .Read and .Read_At, as the underlying stream reports them
    	bytes_written: i64,
    	// by .Write and .Write_At, as the underlying stream reports them
    	calls:         [Stream_Mode]i64,
    	// Only with a nil underlying stream
    	pos:           i64,
    	// where the next .Write lands
    	size:          i64,
    }
     

    Counting_Stream passes everything on to an underlying stream, counting the bytes read and written and how often each mode is used.

    With a nil underlying stream it takes every write and discards it, which measures output without keeping it. It then seeks as a file would, keeping pos and size, so size is how large a file the writes would have made even when they seek back or write at an offset; reads always give .EOF, as nothing written is kept; and flushing, closing and destroying do nothing.

    Related Procedures With Parameters

    Error ¶

    Error :: enum i32 {
    	// No Error
    	None              = 0, 
    	// EOF is the error returned by `read` when no more input is available
    	EOF, 
    	// Unexpected_EOF means that EOF was encountered in the middle of reading a fixed-sized block of data
    	Unexpected_EOF, 
    	// Short_Write means that a write accepted fewer bytes than requested but failed to return an explicit error
    	Short_Write, 
    	// Invalid_Write means that a write returned an impossible count
    	Invalid_Write, 
    	// Short_Buffer means that a read/write required a longer buffer than was provided
    	Short_Buffer, 
    	// No_Progress is returned by some implementations of `io.Reader` when many calls
    	// to `read` have failed to return any data or error.
    	// This is usually a sign of a broken `io.Reader` implementation
    	No_Progress, 
    	// Invalid whence argument
    	Invalid_Whence, 
    	// Invalid offset
    	Invalid_Offset, 
    	// Invalid "unread" operation
    	Invalid_Unread, 
    	Negative_Read, 
    	Negative_Write, 
    	Negative_Count, 
    	Buffer_Full, 
    	// Unknown means that an error has occurred but cannot be categorized
    	Unknown, 
    	// Indicates that an attempt to retrieve a Stream's size was made, but the
    	// stream doesn't have a size.
    	No_Size, 
    	Permission_Denied, 
    	// Stream cannot be used since it has been Closed
    	Closed, 
    	// Unsupported is returned when a procedure has not been implemented for an io.Stream
    	Unsupported       = -1, 
    	Empty             = Unsupported, 
    }

    Related Procedures With Returns

    Limited_Reader ¶

    Limited_Reader :: struct {
    	r: Stream,
    	// underlying reader
    	n: i64,
    }
     

    A Limited_Reader reads from r but limits the amount of data returned to just n bytes. Each call to read updates n to reflect the new amount remaining. read returns EOF when n <= 0 or when the underlying r returns EOF.

    Related Procedures With Parameters

    Multi_Reader ¶

    Multi_Reader :: struct {
    	readers: [dynamic]Stream,
    }

    Related Procedures With Parameters

    Multi_Writer ¶

    Multi_Writer :: struct {
    	writers: [dynamic]Stream,
    }

    Related Procedures With Parameters

    Section_Reader ¶

    Section_Reader :: struct {
    	r:     Stream,
    	base:  i64,
    	off:   i64,
    	limit: i64,
    }
     

    Section_Reader implements read, seek, and read_at on a section of an underlying Reader_At

    Related Procedures With Parameters

    Seek_From ¶

    Seek_From :: enum int {
    	Start   = 0, // seek relative to the origin of the file
    	Current = 1, // seek relative to the current offset
    	End     = 2, // seek relative to the end
    }
     

    Seek whence values

    Stream_Mode ¶

    Stream_Mode :: enum int {
    	Close, 
    	Flush, 
    	Read, 
    	Read_At, 
    	Write, 
    	Write_At, 
    	Seek, 
    	Size, 
    	Destroy, 
    	Query,    // query what modes are available
    }

    Stream_Mode_Set ¶

    Stream_Mode_Set :: distinct bit_set[Stream_Mode; i64]

    Stream_Proc ¶

    Stream_Proc :: proc(stream_data: rawptr, mode: Stream_Mode, p: []u8, offset: i64, whence: Seek_From) -> (n: i64, err: Error)

    Tee_Reader ¶

    Tee_Reader :: struct {
    	r: Stream,
    	w: Stream,
    }

    Related Procedures With Parameters

    Constants

    This section is empty.

    Variables

    This section is empty.

    Procedures

    close ¶

    close :: proc(s: Stream) -> (err: Error) {…}
     

    The behaviour of close after the first call is stream implementation defined. Different streams may document their own behaviour.

    copy ¶

    copy :: proc(dst: Stream, src: Stream) -> (written: i64, err: Error) {…}
     

    copy copies from src to dst till either EOF is reached on src or an error occurs It returns the number of bytes copied and the first error that occurred whilst copying, if any.

    copy_buffer ¶

    copy_buffer :: proc(dst: Stream, src: Stream, buf: []u8) -> (written: i64, err: Error) {…}
     

    copy_buffer is the same as copy except that it stages through the provided buffer (if one is required) rather than allocating a temporary one on the stack through intrinsics.alloca If buf is nil, it is allocate through intrinsics.alloca; otherwise if it has zero length, it will panic

    copy_n ¶

    copy_n :: proc(dst: Stream, src: Stream, n: i64) -> (written: i64, err: Error) {…}
     

    copy_n copies n bytes (or till an error) from src to dst. It returns the number of bytes copied and the first error that occurred whilst copying, if any. On return, written == n iff err == nil

    counting_stream_init ¶

    counting_stream_init :: proc(c: ^Counting_Stream, s: Stream) -> Stream {…}
     

    counting_stream_init returns a Stream that counts what passes through it to 's', with its counts reset. A nil 's' discards every write, keeping only where it would have landed.

    counting_stream_to_stream ¶

    counting_stream_to_stream :: proc(c: ^Counting_Stream) -> (s: Stream) {…}

    destroy ¶

    destroy :: proc(s: Stream) -> (err: Error) {…}

    flush ¶

    flush :: proc(s: Stream) -> (err: Error) {…}

    limited_reader_init ¶

    limited_reader_init :: proc(l: ^Limited_Reader, r: Stream, n: i64) -> Stream {…}

    limited_reader_to_reader ¶

    limited_reader_to_reader :: proc(l: ^Limited_Reader) -> (r: Stream) {…}

    multi_reader_destroy ¶

    multi_reader_destroy :: proc(mr: ^Multi_Reader) {…}

    multi_reader_init ¶

    multi_reader_init :: proc(
    	mr:        ^Multi_Reader, 
    	readers:   ..Stream, 
    	allocator := context.allocator, 
    ) -> (r: Stream) {…}

    multi_writer_destroy ¶

    multi_writer_destroy :: proc(mw: ^Multi_Writer) {…}

    multi_writer_init ¶

    multi_writer_init :: proc(
    	mw:        ^Multi_Writer, 
    	writers:   ..Stream, 
    	allocator := context.allocator, 
    ) -> (out: Stream) {…}

    query ¶

    query :: proc(s: Stream) -> (set: Stream_Mode_Set) {…}

    query_utility ¶

    query_utility :: proc "contextless" (set: Stream_Mode_Set) -> (n: i64, err: Error) {…}

    read ¶

    read :: proc(s: Stream, p: []u8, n_read: ^int = nil) -> (n: int, err: Error) {…}
     

    read reads up to len(p) bytes into p. It returns the number of bytes read and any error if occurred.

    When read encounters an .EOF or error after successfully reading n > 0 bytes, it returns the number of bytes read along with the error.

    read_at ¶

    read_at :: proc(r: Stream, p: []u8, offset: i64, n_read: ^int = nil) -> (n: int, err: Error) {…}
     

    read_at reads len(p) bytes into p starting with the provided offset in the underlying Reader_At stream r. It returns the number of bytes read and any error if occurred.

    When read_at returns n < len(p), it returns a non-nil Error explaining why.

    If n == len(p), err may be either nil or .EOF

    read_at_least ¶

    read_at_least :: proc(r: Stream, buf: []u8, min: int) -> (n: int, err: Error) {…}
     

    read_at_least reads from r into buf until it has read at least min bytes. It returns the number of bytes copied and an error if fewer bytes were read. .EOF is only returned if no bytes were read. .Unexpected_EOF is returned when an .EOF is returned by the passed Reader after reading fewer than min bytes. If len(buf) is less than min, .Short_Buffer is returned.

    read_byte ¶

    read_byte :: proc(r: Stream, n_read: ^int = nil) -> (b: u8, err: Error) {…}
     

    read_byte reads and returns the next byte from r.

    read_full ¶

    read_full :: proc(r: Stream, buf: []u8) -> (n: int, err: Error) {…}
     

    read_full expected exactly len(buf) bytes from r into buf.

    read_full_at ¶

    read_full_at :: proc(r: Stream, buf: []u8, offset: i64) -> (n: int, err: Error) {…}

    read_ptr ¶

    read_ptr :: proc(
    	r:         Stream, 
    	p:         rawptr, 
    	byte_size: int, 
    	n_read:    ^int = nil, 
    ) -> (n: int, err: Error) {…}

    read_ptr_at ¶

    read_ptr_at :: proc(
    	r:         Stream, 
    	p:         rawptr, 
    	byte_size: int, 
    	offset:    i64, 
    	n_read:    ^int = nil, 
    ) -> (n: int, err: Error) {…}

    read_rune ¶

    read_rune :: proc(br: Stream, n_read: ^int = nil) -> (ch: rune, size: int, err: Error) {…}
     

    read_rune reads a single UTF-8 encoded Unicode codepoint and returns the rune and its size in bytes.

    read_slice ¶

    read_slice :: proc(r: Stream, slice: $S/[]$T, n_read: ^int = nil) -> (n: int, err: Error) {…}

    section_reader_init ¶

    section_reader_init :: proc(s: ^Section_Reader, r: Stream, off: i64, n: i64) -> Stream {…}

    section_reader_to_stream ¶

    section_reader_to_stream :: proc(s: ^Section_Reader) -> (out: Stream) {…}

    seek ¶

    seek :: proc(s: Stream, offset: i64, whence: Seek_From) -> (n: i64, err: Error) {…}
     

    seek sets the offset of the next read or write to offset.

    .Start means seek relative to the origin of the file. .Current means seek relative to the current offset. .End means seek relative to the end.

    seek returns the new offset to the start of the file/stream, and any error if occurred.

    size ¶

    size :: proc(s: Stream) -> (n: i64, err: Error) {…}
     

    size returns the size of the stream. If the stream does not support querying its size, 0 will be returned.

    tee_reader_init ¶

    tee_reader_init :: proc(
    	t:         ^Tee_Reader, 
    	r:         Stream, 
    	w:         Stream, 
    	allocator := context.allocator, 
    ) -> Stream {…}
     

    tee_reader_init returns a Reader that writes to 'w' what it reads from 'r' All reads from 'r' performed through it are matched with a corresponding write to 'w' There is no internal buffering done The write must complete before th read completes Any error encountered whilst writing is reported as a 'read' error tee_reader_init must call io.destroy when done with

    tee_reader_to_reader ¶

    tee_reader_to_reader :: proc(t: ^Tee_Reader) -> (r: Stream) {…}

    to_closer ¶

    to_closer :: proc(s: Stream) -> (c: Stream, ok: bool = true) #optional_ok {…}

    to_flusher ¶

    to_flusher :: proc(s: Stream) -> (f: Stream, ok: bool = true) #optional_ok {…}

    to_read_closer ¶

    to_read_closer :: proc(s: Stream) -> (r: Stream, ok: bool = true) #optional_ok {…}

    to_read_write_closer ¶

    to_read_write_closer :: proc(s: Stream) -> (r: Stream, ok: bool = true) #optional_ok {…}

    to_read_write_seeker ¶

    to_read_write_seeker :: proc(s: Stream) -> (r: Stream, ok: bool = true) #optional_ok {…}

    to_read_writer ¶

    to_read_writer :: proc(s: Stream) -> (r: Stream, ok: bool = true) #optional_ok {…}

    to_reader ¶

    to_reader :: proc(s: Stream) -> (r: Stream, ok: bool = true) #optional_ok {…}

    to_reader_at ¶

    to_reader_at :: proc(s: Stream) -> (r: Stream, ok: bool = true) #optional_ok {…}

    to_seeker ¶

    to_seeker :: proc(s: Stream) -> (seeker: Stream, ok: bool = true) #optional_ok {…}

    to_write_closer ¶

    to_write_closer :: proc(s: Stream) -> (w: Stream, ok: bool = true) #optional_ok {…}

    to_write_flush_closer ¶

    to_write_flush_closer :: proc(s: Stream) -> (w: Stream, ok: bool = true) #optional_ok {…}

    to_write_flusher ¶

    to_write_flusher :: proc(s: Stream) -> (w: Stream, ok: bool = true) #optional_ok {…}

    to_write_seeker ¶

    to_write_seeker :: proc(s: Stream) -> (w: Stream, ok: bool = true) #optional_ok {…}

    to_writer ¶

    to_writer :: proc(s: Stream) -> (w: Stream, ok: bool = true) #optional_ok {…}

    to_writer_at ¶

    to_writer_at :: proc(s: Stream) -> (w: Stream, ok: bool = true) #optional_ok {…}

    write ¶

    write :: proc(s: Stream, p: []u8, n_written: ^int = nil) -> (n: int, err: Error) {…}
     

    write writes up to len(p) bytes into p. It returns the number of bytes written and any error if occurred.

    write_at ¶

    write_at :: proc(
    	w:         Stream, 
    	p:         []u8, 
    	offset:    i64, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}
     

    write_at writes len(p) bytes into p starting with the provided offset in the underlying Writer_At stream w. It returns the number of bytes written and any error if occurred.

    If write_at is writing to a Writer_At which has a seek offset, then write_at should not affect the underlying seek offset.

    write_at_least ¶

    write_at_least :: proc(w: Stream, buf: []u8, min: int) -> (n: int, err: Error) {…}
     

    write_at_least writes at least buf[:min] to the writer and returns the amount written. If an error occurs before writing everything it is returned.

    write_byte ¶

    write_byte :: proc(w: Stream, c: u8, n_written: ^int = nil) -> Error {…}

    write_encoded_and_escaped_rune ¶

    write_encoded_and_escaped_rune :: proc(
    	w:         Stream, 
    	r:         rune, 
    	quote:     u8, 
    	options:   bit_set[strconv.Rune_Escaping_Option] = nil, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes rune r to the Writer w as UTF-8, escaping it as needed and escaping quote when it occurs.

    Inputs:

    • w: The Writer to write to.
    • r: The rune to write.
    • quote: An enclosing quote character to escape; pass 0 to disable quote-character escaping.
    • options: Controls how the rune is escaped.
    • n_written: Optional pointer to a counter to which the number of bytes written is added.

    Returns:

    • n: The number of bytes written.
    • err: An error encountered while writing, or nil on success.

    Remarks:

    The rune is not surrounded by quotes. Use write_quoted_rune or write_quoted_string to produce quoted output.

    If the Writer writes only part of the output before returning an error, n reports the number of bytes written.

    write_encoded_rune ¶

    write_encoded_rune :: proc(
    	w:           Stream, 
    	r:           rune, 
    	write_quote: bool = true, 
    	n_written:   ^int = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes rune r to the Writer w as UTF-8, optionally enclosed in single quotes.

    Inputs:

    • w: The Writer to write to.
    • r: The rune to write.
    • write_quote: If true (the default), writes the rune as a quoted rune literal; otherwise writes it unquoted.
    • n_written: Optional pointer to a counter to which the number of bytes written is added.

    Returns:

    • n: The number of bytes written.
    • err: An error encountered while writing, or nil on success.

    Remarks:

    When write_quote is true, the output is escaped and quoted as a rune literal.

    When write_quote is false, the rune is written unquoted and neither single nor double quotes are escaped.

    If the Writer writes only part of the output before returning an error, n reports the number of bytes written.

    write_escaped_rune ¶

    write_escaped_rune :: proc(
    	w:         Stream, 
    	r:         rune, 
    	quote:     u8, 
    	html_safe: bool = false, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes rune r to the Writer w as UTF-8, escaping it as needed and escaping quote when it occurs.

    Inputs:

    • w: The Writer to write to.
    • r: The rune to write.
    • quote: An enclosing quote character to escape; pass 0 to disable quote-character escaping.
    • html_safe: If true, also escapes <, > and & using hexadecimal escapes (\x##).
    • n_written: Optional pointer to a counter to which the number of bytes written is added.

    Returns:

    • n: The number of bytes written.
    • err: An error encountered while writing, or nil on success.

    Remarks:

    The rune is not surrounded by quotes. For quoted output, use write_quoted_rune or write_quoted_string.

    If the Writer writes only part of the output before returning an error, n reports the number of bytes written.

    write_f16 ¶

    write_f16 :: proc(w: Stream, val: f16, n_written: ^int = nil) -> (n: int, err: Error) {…}

    write_f32 ¶

    write_f32 :: proc(w: Stream, val: f32, n_written: ^int = nil) -> (n: int, err: Error) {…}

    write_f64 ¶

    write_f64 :: proc(w: Stream, val: f64, n_written: ^int = nil) -> (n: int, err: Error) {…}

    write_full ¶

    write_full :: proc(w: Stream, buf: []u8) -> (n: int, err: Error) {…}
     

    write_full writes until the entire contents of buf has been written or an error occurs.

    write_i128 ¶

    write_i128 :: proc(
    	w:         Stream, 
    	i:         i128, 
    	base:      int = 10, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_i64 ¶

    write_i64 :: proc(
    	w:         Stream, 
    	i:         i64, 
    	base:      int = 10, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_int ¶

    write_int :: proc(
    	w:         Stream, 
    	i:         int, 
    	base:      int = 10, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_ptr ¶

    write_ptr :: proc(
    	w:         Stream, 
    	p:         rawptr, 
    	byte_size: int, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_ptr_at ¶

    write_ptr_at :: proc(
    	w:         Stream, 
    	p:         rawptr, 
    	byte_size: int, 
    	offset:    i64, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_quoted_rune ¶

    write_quoted_rune :: proc(
    	w:         Stream, 
    	r:         rune, 
    	options:   bit_set[strconv.Rune_Escaping_Option] = nil, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes rune r to the Writer w as a quoted rune literal, escaping it as needed.

    Inputs:

    • w: The Writer to write to.
    • r: The rune to quote and write.
    • options: Controls how the rune is escaped.
    • n_written: Optional pointer to a counter to which the number of bytes written is added.

    Returns:

    • n: The number of bytes written.
    • err: An error encountered while writing, or nil on success.

    Remarks:

    The result is enclosed in single quotes. If the Writer writes only part of the output before returning an error, n reports the number of bytes written.

    write_quoted_string ¶

    write_quoted_string :: proc(
    	w:         Stream, 
    	str:       string, 
    	quote:     u8 = '"', 
    	n_written: ^int = nil, 
    	options:   bit_set[strconv.Rune_Escaping_Option] = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes str to the Writer w, enclosed in quote characters, escaping runes as needed.

    Inputs:

    • w: The Writer to write to.
    • str: The string to quote and write.
    • quote: The enclosing quote character (double quote by default).
    • n_written: Optional pointer to a counter to which the number of bytes written is added.
    • options: Controls how runes in the string are escaped.

    Returns:

    • n: The number of bytes written.
    • err: An error encountered while writing, or nil on success.

    Remarks:

    With the default double quote and escaping options, the output is quoted and escaped as an Odin string literal.

    Invalid UTF-8 bytes in str are written as hexadecimal byte escapes. If the Writer writes only part of the output before returning an error, n reports the number of bytes written.

    write_quoted_string16 ¶

    write_quoted_string16 :: proc(
    	w:         Stream, 
    	str:       string16, 
    	quote:     u8 = '"', 
    	n_written: ^int = nil, 
    	options:   bit_set[strconv.Rune_Escaping_Option] = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes str to the Writer w, enclosed in quote characters, escaping runes as needed.

    NOTE: The UTF-16 input string is encoded as UTF-8 in the output.

    Inputs:

    • w: The Writer to write to.
    • str: The UTF-16 string to quote and write.
    • quote: The enclosing quote character (double quote by default).
    • n_written: Optional pointer to a counter to which the number of bytes written is added.
    • options: Controls how runes in the string are escaped.

    Returns:

    • n: The number of UTF-8 bytes written.
    • err: An error encountered while writing, or nil on success.

    Remarks:

    With the default double quote and escaping options, the output is quoted and escaped as an Odin string literal.

    Unpaired UTF-16 surrogates are encoded as the Unicode replacement character. The UTF-16 decoder does not distinguish malformed sequences from literal replacement characters, so both are written identically.

    If the Writer writes only part of the output before returning an error, n reports the number of bytes written.

    write_rune ¶

    write_rune :: proc(s: Stream, r: rune, n_written: ^int = nil) -> (size: int, err: Error) {…}
     

    write_rune writes a UTF-8 encoded rune to w.

    write_slice ¶

    write_slice :: proc(w: Stream, slice: $S/[]$T, n_written: ^int = nil) -> (n: int, err: Error) {…}

    write_string ¶

    write_string :: proc(s: Stream, str: string, n_written: ^int = nil) -> (n: int, err: Error) {…}
     

    Writes the UTF-8 bytes of str to the Writer w without modification.

    Inputs:

    • w: The Writer to write to.
    • str: The string whose bytes are written.
    • n_written: Optional pointer to a counter to which the number of bytes written is added.

    Returns:

    • n: The number of bytes written.
    • err: An error encountered while writing, or nil on success.

    If the Writer writes only part of the string before returning an error, n reports the number of bytes written.

    write_string16 ¶

    write_string16 :: proc(
    	w:         Stream, 
    	str:       string16, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}
     

    Writes the UTF-16 string str to the Writer w, encoded as UTF-8.

    Inputs:

    • w: The Writer to write to.
    • str: The UTF-16 string to encode and write.
    • n_written: Optional pointer to a counter to which the number of bytes written is added for each successfully written rune.

    Returns:

    • n: The number of UTF-8 bytes written.
    • err: An error encountered while writing, or nil on success.

    Unpaired UTF-16 surrogates are encoded as the Unicode replacement character. The UTF-16 decoder does not distinguish malformed sequences from literal replacement characters, so both are written identically.

    write_u128 ¶

    write_u128 :: proc(
    	w:         Stream, 
    	i:         u128, 
    	base:      int = 10, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_u64 ¶

    write_u64 :: proc(
    	w:         Stream, 
    	i:         u64, 
    	base:      int = 10, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    write_uint ¶

    write_uint :: proc(
    	w:         Stream, 
    	i:         uint, 
    	base:      int = 10, 
    	n_written: ^int = nil, 
    ) -> (n: int, err: Error) {…}

    Procedure Groups

    This section is empty.

    Source Files

    Generation Information

    Generated with odin version dev-2026-11 (vendor "odin") Windows_amd64 @ 2026-11-18 21:05:19.828955300 +0000 UTC