API
#ioBuffer / Cursor, stream copying, EOF/error results with data, and write-progress contracts; also multi/tee/section/pipe.
struct@ Writerstruct@ Writer {
fn write(&string) int
}Writer / Reader are the legacy -shaped method sets (structural). copy is Cursor→Buffer and returns owned string. stream.xu supplies generic borrowed StreamReader/StreamWriter copying with bounded owning string chunks. copy_to returns Buffer. Cursor/SectionCursor provide seek/read_at.
write fn write(&string) int(Writer) writefn write(&string) intMethod on `Writer`: write data and return the byte count.
self Selfstring &stringint — bytes written
struct@ Readerstruct@ Reader {
fn read_n(int) string
}Method-set constraint `Reader`. Implementing types must provide the methods below. Not an interface value.
read_n fn read_n(int) string(Reader) read_nfn read_n(int) stringMethod on `Reader`: read at most n bytes; may return shorter or empty at end.
self Selfint intstring — result string
struct Bufferpub struct Buffer {
pub data string
pub off int
}Public struct `Buffer`.
data stringoff intstruct Cursorpub struct Cursor {
pub data string
pub off int
}Public struct `Cursor`.
data stringoff intbufferpub fn buffer() Bufferbuffer; returns Buffer.
none
Buffer — a value of this type
buffer_frompub fn buffer_from(s string) BufferBuffer from.
s stringBuffer — a value of this type
cursorpub fn cursor(s string) Cursorcursor; returns Cursor.
s stringCursor — a value of this type
(&mut Cursor) resetpub fn (c &mut Cursor) reset(s string)Method on `&mut Cursor`: clear internal state so the value can be reused.
c &mut Cursors string(&mut Buffer) resetpub fn (b &mut Buffer) reset()Method on `&mut Buffer`: clear internal state so the value can be reused.
b &mut Buffer(&Buffer) lenpub fn (b &Buffer) len() intMethod on `&Buffer`: return the length.
b &Bufferint — a value of this type
(&Buffer) cappub fn (b &Buffer) cap() intMethod on `&Buffer`: return the capacity.
b &Bufferint — a value of this type
(&Cursor) sizepub fn (c &Cursor) size() intMethod on `&Cursor`: return the size.
c &Cursorint — a value of this type
(&mut Buffer) writepub fn (b &mut Buffer) write(data &string) intMethod on `&mut Buffer`: write data and return the byte count.
b &mut Bufferdata &stringint — bytes written
(&mut Buffer) write_strpub fn (b &mut Buffer) write_str(s string) intwrite_str appends an owned string without requiring a borrow of a local.
b &mut Buffers stringint — a value of this type
(&mut Buffer) write_bytepub fn (b &mut Buffer) write_byte(c int) intMethod on `&mut Buffer`: write one byte.
b &mut Bufferc intint — bytes written
(&mut Buffer) read_npub fn (b &mut Buffer) read_n(n int) stringMethod on `&mut Buffer`: read at most n bytes; may return shorter or empty at end.
b &mut Buffern intstring — result string
(&Buffer) bytespub fn (b &Buffer) bytes() stringMethod on `&Buffer`: return the buffered bytes.
b &Bufferstring — result string
(&mut Cursor) read_npub fn (c &mut Cursor) read_n(n int) stringMethod on `&mut Cursor`: read at most n bytes; may return shorter or empty at end.
c &mut Cursorn intstring — result string
copypub fn copy(dst Buffer, src Cursor) stringcopy drains src into dst and returns the remaining dst bytes as a string.
dst Buffersrc Cursorstring — result string
copy_topub fn copy_to(dst Buffer, src Cursor) Buffercopy_to is the Buffer-returning form.
dst Buffersrc CursorBuffer — a value of this type
read_allpub fn read_all(src Cursor) stringRead all.
src Cursorstring — result string
const eofpub const eof = "EOF"Public constant `eof`. Value `"EOF"`.
none
(&Cursor) remainingpub fn (c &Cursor) remaining() intCall `remaining` on `&Cursor`.
c &Cursorint — a value of this type
(&mut Cursor) seekpub fn (c &mut Cursor) seek(offset int, whence int) intMethod on `&mut Cursor`: move the read position. whence 0/1/2 = absolute / relative / from end. Throws on failure.
c &mut Cursoroffset intwhence intint — a value of this type
(&Cursor) read_atpub fn (c &Cursor) read_at(n int, off int) stringMethod on `&Cursor`: read at most n bytes starting at offset off. Throws on failure.
c &Cursorn intoff intstring — result string
read_fullpub fn read_full(src Cursor, n int) stringRead full.
src Cursorn intstring — result string
read_at_leastpub fn read_at_least(src Cursor, min int, max int) stringRead at least. Throws on failure.
src Cursormin intmax intstring — result string
copy_npub fn copy_n(dst Buffer, src Cursor, n int) stringCopy n. Throws on failure.
dst Buffersrc Cursorn intstring — result string
struct LimitCursorpub struct LimitCursor {
pub src Cursor
pub n int
}Public struct `LimitCursor`.
src Cursorn intlimit_cursorpub fn limit_cursor(src Cursor, n int) LimitCursorLimit cursor.
src Cursorn intLimitCursor — a value of this type
(LimitCursor) remainingpub fn (l LimitCursor) remaining() intCall `remaining` on `LimitCursor`.
l LimitCursorint — a value of this type
(&mut LimitCursor) read_npub fn (l &mut LimitCursor) read_n(n int) stringMethod on `&mut LimitCursor`: read at most n bytes; may return shorter or empty at end.
l &mut LimitCursorn intstring — result string
struct Discardpub struct Discard {
pub n int
}Public struct `Discard`.
n intdiscardpub fn discard() Discarddiscard; returns Discard.
none
Discard — a value of this type
(&mut Discard) writepub fn (d &mut Discard) write(data &string) intMethod on `&mut Discard`: write data and return the byte count.
d &mut Discarddata &stringint — bytes written
(Discard) writtenpub fn (d Discard) written() intCall `written` on `Discard`.
d Discardint — a value of this type
struct MultiCursorpub struct MultiCursor {
pub chunks []string
pub i int
pub off int
}Concatenate string snapshots ( MultiReader, bound to Cursor-shaped chunks — no generic Reader). One read_n drains the current chunk only empty/exhausted chunks are skipped in the same call.
chunks []stringi intoff intmulti_cursorpub fn multi_cursor(parts <-> string) MultiCursorMulti cursor.
parts <-> stringMultiCursor — a value of this type
(&mut MultiCursor) read_npub fn (m &mut MultiCursor) read_n(n int) stringMethod on `&mut MultiCursor`: read at most n bytes; may return shorter or empty at end.
m &mut MultiCursorn intstring — result string
struct MultiBufferpub struct MultiBuffer {
pub parts []string
}Write the same bytes to n owning destinations ( MultiWriter).
parts []stringmulti_bufferpub fn multi_buffer(n int) MultiBufferMulti buffer.
n intMultiBuffer — a value of this type
(&mut MultiBuffer) writepub fn (m &mut MultiBuffer) write(data &string) intMethod on `&mut MultiBuffer`: write data and return the byte count.
m &mut MultiBufferdata &stringint — bytes written
(&MultiBuffer) textpub fn (m &MultiBuffer) text(i int) stringMethod on `&MultiBuffer`: return the current text.
m &MultiBufferi intstring — result string
struct Teepub struct Tee {
pub src Cursor
pub dst Buffer
}Read from src, copy each chunk into dst ( TeeReader).
src Cursordst Bufferteepub fn tee(src Cursor, dst Buffer) Teetee; returns Tee.
src Cursordst BufferTee — a value of this type
(&mut Tee) read_npub fn (t &mut Tee) read_n(n int) stringMethod on `&mut Tee`: read at most n bytes; may return shorter or empty at end.
t &mut Teen intstring — result string
(&Tee) copiedpub fn (t &Tee) copied() stringCall `copied` on `&Tee`.
t &Teestring — result string
struct SectionCursorpub struct SectionCursor {
pub data string
pub base int
pub limit int
pub off int
}Window into a string snapshot ( SectionReader + ReadAt/Seek).
data stringbase intlimit intoff intsection_cursorpub fn section_cursor(s string, off int, n int) SectionCursorSection cursor.
s stringoff intn intSectionCursor — a value of this type
(&mut SectionCursor) read_npub fn (s &mut SectionCursor) read_n(n int) stringMethod on `&mut SectionCursor`: read at most n bytes; may return shorter or empty at end.
s &mut SectionCursorn intstring — result string
(&SectionCursor) sizepub fn (s &SectionCursor) size() intMethod on `&SectionCursor`: return the size.
s &SectionCursorint — a value of this type
(&mut SectionCursor) seekpub fn (s &mut SectionCursor) seek(offset int, whence int) intMethod on `&mut SectionCursor`: move the read position. whence 0/1/2 = absolute / relative / from end. Throws on failure.
s &mut SectionCursoroffset intwhence intint — a value of this type
(&SectionCursor) read_atpub fn (s &SectionCursor) read_at(n int, off int) stringMethod on `&SectionCursor`: read at most n bytes starting at offset off. Throws on failure.
s &SectionCursorn intoff intstring — result string
struct PipeReaderpub struct PipeReader {
pub r chan string
pub buf string
pub off int
}In-memory one-way pipe ( io.Pipe shape; queue is a bounded chan like net.pipe, not a synchronous unbuffered handshake).
r chan stringbuf stringoff intstruct PipeWriterpub struct PipeWriter {
pub w chan string
pub closed int
}Public struct `PipeWriter`.
w chan stringclosed intstruct Pipepub struct Pipe {
pub r PipeReader
pub w PipeWriter
}Public struct `Pipe`.
r PipeReaderw PipeWriterpipepub fn pipe() Pipepipe; returns Pipe.
none
Pipe — a value of this type
(&mut PipeReader) read_npub fn (p &mut PipeReader) read_n(n int) stringMethod on `&mut PipeReader`: read at most n bytes; may return shorter or empty at end.
p &mut PipeReadern intstring — result string
(PipeWriter) writepub fn (w PipeWriter) write(data &string) intMethod on `PipeWriter`: write data and return the byte count. Throws on failure.
w PipeWriterdata &stringint — bytes written
(&mut PipeWriter) closepub fn (w &mut PipeWriter) close() intMethod on `&mut PipeWriter`: close the resource.
w &mut PipeWriterint — a value of this type
enum ReadResultpub enum ReadResult {
Data(string)
End(string)
Failed(string, errors.Error)
}Owned chunks; terminal conditions may accompany the last bytes.
none
enum WriteResultpub enum WriteResult {
Written(int)
Failed(int, errors.Error)
Unknown(errors.Error)
}Counts acknowledge a prefix of this call's input. Unknown is required when a legacy operation throws after effects it cannot quantify.
none
enum CopyResultpub enum CopyResult {
Copied(int)
Failed(int, errors.Error)
Uncertain(int, errors.Error)
}Failed has an exact accepted count; Uncertain has a confirmed lower bound.
none
struct@ ProgressReaderpub struct@ ProgressReader {
fn read_result(int) ReadResult
}Method-set constraint `ProgressReader`. Implementing types must provide the methods below. Not an interface value.
read_result fn read_result(int) ReadResult(ProgressReader) read_resultfn read_result(int) ReadResultMethod on `ProgressReader`: read result.
self Selfint intReadResult — a value of this type
struct@ ProgressWriterpub struct@ ProgressWriter {
fn write_result(string) WriteResult
}Method-set constraint `ProgressWriter`. Implementing types must provide the methods below. Not an interface value.
write_result fn write_result(string) WriteResult(ProgressWriter) write_resultfn write_result(string) WriteResultMethod on `ProgressWriter`: write result.
self Selfstring stringWriteResult — a value of this type
struct LegacyReader#R:StreamReaderpub struct LegacyReader#R:StreamReader {
pub src R
}Legacy readers cannot recover bytes that were lost when throwing.
src Rstruct LegacyWriter#W:StreamWriterpub struct LegacyWriter#W:StreamWriter {
pub dst W
}Public struct `LegacyWriter#W:StreamWriter`.
dst Wprogress_readerpub fn progress_reader#R:StreamReader(src R) LegacyReader#RProgress reader.
src RLegacyReader#R — a value of this type
progress_writerpub fn progress_writer#W:StreamWriter(dst W) LegacyWriter#WProgress writer.
dst WLegacyWriter#W — a value of this type
(&mut LegacyReader#R) read_resultpub fn (r &mut LegacyReader#R) read_result(n int) ReadResultMethod on `&mut LegacyReader#R`: read result.
r &mut LegacyReader#Rn intReadResult — a value of this type
(&mut LegacyWriter#W) write_resultpub fn (w &mut LegacyWriter#W) write_result(data string) WriteResultMethod on `&mut LegacyWriter#W`: write result.
w &mut LegacyWriter#Wdata stringWriteResult — a value of this type
copy_resultpub fn copy_result#W:ProgressWriter,R:ProgressReader(dst &mut W, src &mut R) CopyResultCopy result.
dst &mut Wsrc &mut RCopyResult — a value of this type
copy_result_bufferpub fn copy_result_buffer#W:ProgressWriter,R:ProgressReader(dst &mut W, src &mut R, size int) CopyResultCopy result buffer.
dst &mut Wsrc &mut Rsize intCopyResult — a value of this type
copy_result_npub fn copy_result_n#W:ProgressWriter,R:ProgressReader(dst &mut W, src &mut R, n int) CopyResultCopy result n.
dst &mut Wsrc &mut Rn intCopyResult — a value of this type
(&mut Cursor) read_resultpub fn (c &mut Cursor) read_result(n int) ReadResultMethod on `&mut Cursor`: read result.
c &mut Cursorn intReadResult — a value of this type
(&mut Buffer) read_resultpub fn (b &mut Buffer) read_result(n int) ReadResultMethod on `&mut Buffer`: read result.
b &mut Buffern intReadResult — a value of this type
(&mut Buffer) write_resultpub fn (b &mut Buffer) write_result(data string) WriteResultMethod on `&mut Buffer`: write result.
b &mut Bufferdata stringWriteResult — a value of this type
(&mut Discard) write_resultpub fn (d &mut Discard) write_result(data string) WriteResultMethod on `&mut Discard`: write result.
d &mut Discarddata stringWriteResult — a value of this type
enum ReadIntopub enum ReadInto {
Filled(int)
End(int)
Failed(int, errors.Error)
}ReadInto reports how many bytes were stored in the caller's buffer. The destination is exclusively borrowed for the call and is never grown. The result owns only the count and error; it does not borrow the buffer. Bytes outside the written prefix stay unchanged. A zero count performs no I/O.
none
(&mut Cursor) read_intopub fn (c &mut Cursor) read_into(dst &mut []int, off int, n int) ReadIntoMethod on `&mut Cursor`: read into.
c &mut Cursordst &mut []intoff intn intReadInto — a value of this type
(&mut Buffer) read_intopub fn (b &mut Buffer) read_into(dst &mut []int, off int, n int) ReadIntoMethod on `&mut Buffer`: read into.
b &mut Bufferdst &mut []intoff intn intReadInto — a value of this type
read_intopub fn read_into#R:ProgressReader(src &mut R, dst &mut []int, off int, n int) ReadIntoOne synchronous read_result, then a copy into the exclusive window. The temporary owned chunk dies before return. Invalid counts are not stored. This does not retry and does not replace Cursor/Buffer.read_into.
src &mut Rdst &mut []intoff intn intReadInto — a value of this type
struct@ StreamReaderpub struct@ StreamReader {
fn read_n(int) string
}read_n(n>0) returns at most n bytes. Empty string or an error with message eof ends the stream; other errors propagate. Unlike Reader, this API cannot return bytes and an error in the same operation.
read_n fn read_n(int) string(StreamReader) read_nfn read_n(int) stringMethod on `StreamReader`: read at most n bytes; may return shorter or empty at end.
self Selfint intstring — result string
struct@ StreamWriterpub struct@ StreamWriter {
fn write_str(string) int
}write_str consumes one owning chunk. It must accept the whole chunk or throw; returning a shorter count is a short write, never an invitation to replay a partially accepted chunk. The destination may retain data itself.
write_str fn write_str(string) int(StreamWriter) write_strfn write_str(string) intMethod on `StreamWriter`: write a string.
self Selfstring stringint — a value of this type
copy_streampub fn copy_stream#W:StreamWriter,R:StreamReader(dst &mut W, src &mut R) intThe three public forms retain their independently tested copy contracts. Generic forwarding is supported; no additional whole-stream staging is used. Both endpoints are borrowed; their partial effects remain visible on errors. Throws on failure.
dst &mut Wsrc &mut Rint — a value of this type
copy_stream_bufferpub fn copy_stream_buffer#W:StreamWriter,R:StreamReader(dst &mut W, src &mut R, size int) intMaximum owning chunk size, with no whole-stream staging. Throws on failure.
dst &mut Wsrc &mut Rsize intint — a value of this type
copy_stream_npub fn copy_stream_n#W:StreamWriter,R:StreamReader(dst &mut W, src &mut R, n int) intExactly n bytes, with no over-read. n=0 touches neither endpoint. Throws on failure.
dst &mut Wsrc &mut Rn intint — a value of this type
(&mut Discard) write_strpub fn (d &mut Discard) write_str(data string) intMethod on `&mut Discard`: write a string.
d &mut Discarddata stringint — a value of this type