cursor
import std::io::cursor; · source
Types
Cursor
type struct Cursor {
buffer: Array<u8>;
pos: u64;
static new(buffer: Array<u8>) -> Cursor;
static empty() -> Cursor;
position(&this) -> u64;
set_position(mut &this, pos: u64) -> void;
len(&this) -> u64;
as_bytes(&this) -> Slice<u8>;
into_inner(mut &this) -> Array<u8>;
}An in-memory byte buffer that is Read, Write, and Seek. This is how you run code written against the I/O traits against memory instead of a file or socket — the standard way to unit-test a reader or writer, or to build up a payload before handing it to a real sink.
import std::io::cursor;
mut c: Cursor = Cursor::empty();
c.write(header);
c.write(body);
mut bytes: Array<u8> = c.into_inner();new(buffer) takes ownership of an existing buffer with the cursor at 0; empty() starts fresh. into_inner() moves the buffer out and leaves the cursor holding a fresh empty one.
Reads copy forward and return 0 at the end. Writes overwrite the bytes under the cursor and extend past the end; a write starting beyond the current end zero-fills the gap first, matching the sparse region a File seek-past-end leaves. Reads never error, and writes fail only on allocation failure, surfaced as WriteZero.
Properties
| Property | Type |
|---|---|
buffer | Array<u8> |
pos | u64 |
Constructors
static new(buffer: Array<u8>) -> Cursor;
static new(buffer: Array<u8>) -> Cursor;Wrap an existing byte buffer with the cursor at position 0. Takes ownership of buffer; reads start at its first byte.
static empty() -> Cursor;
static empty() -> Cursor;A cursor over a fresh empty buffer - the usual starting point for accumulating bytes with write.
Methods
position(&this) -> u64;
position(&this) -> u64;Current cursor position: the absolute byte offset from the start where the next read or write lands. Independent of the buffer length; may exceed it after a seek-past-end.
set_position(mut &this, pos: u64) -> void;
set_position(mut &this, pos: u64) -> void;Set the cursor position directly. Positions past the buffer end are allowed and behave as documented on the type.
len(&this) -> u64;
len(&this) -> u64;Number of bytes currently in the buffer, independent of the cursor position.
as_bytes(&this) -> Slice<u8>;
as_bytes(&this) -> Slice<u8>;Borrow the buffered bytes without moving the cursor. The slice is invalidated by any subsequent write (which may reallocate).
into_inner(mut &this) -> Array<u8>;
into_inner(mut &this) -> Array<u8>;Move the buffer out, leaving the cursor holding a fresh empty buffer. The typical "collect the written bytes" finisher; the cursor stays valid and must still be dropped.
Trait implementations
implement trait Read for struct Cursor
implement trait Write for struct Cursor
implement trait Seek for struct Cursor
implement trait Drop for struct Cursor
type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.
type struct Name {
field: Type;
method(&this) -> Ret { ... }
}A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.
type struct Cursor {
buffer: Array<u8>;
pos: u64;
}An in-memory Read + Write + Seek byte buffer. Owns its Array<u8>; drop releases it (or move it out with into_inner first).
Cursor.buffer: Array<u8>type struct Array<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
length: i64;
capacity: i64;
alloc: A;
}Array<T, A>: growable, heap-backed, contiguous sequence.
std::collections::arrayCursor.pos: u64static name(param: Type) -> Ret { ... }A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.
static Cursor::new(buffer: Array<u8>) -> CursorWrap an existing byte buffer with the cursor at position 0. Takes ownership of buffer; reads start at its first byte.
(parameter) buffer: Array<u8>type struct Cursor {
buffer: Array<u8>;
pos: u64;
}An in-memory Read + Write + Seek byte buffer. Owns its Array<u8>; drop releases it (or move it out with into_inner first).
static Cursor::empty() -> CursorA cursor over a fresh empty buffer - the usual starting point for accumulating bytes with write.
Cursor::position(&this) -> u64Current cursor position: the absolute byte offset from the start where the next read or write lands. Independent of the buffer length; may exceed it after a seek-past-end.
&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
Cursor::set_position(mut &this, pos: u64) -> voidSet the cursor position directly. Positions past the buffer end are allowed and behave as documented on the type.
mut &this
mut &TypeAn exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.
(parameter) pos: u64Cursor::len(&this) -> u64Number of bytes currently in the buffer, independent of the cursor position.
Cursor::as_bytes(&this) -> Slice<u8>Borrow the buffered bytes without moving the cursor. The slice is invalidated by any subsequent write (which may reallocate).
type struct Slice<T> {
ptr: T*;
length: u64;
}Slice<T>: a borrowed view into a contiguous sequence.
std::core::sliceCursor::into_inner(mut &this) -> Array<u8>Move the buffer out, leaving the cursor holding a fresh empty buffer. The typical "collect the written bytes" finisher; the cursor stays valid and must still be dropped.
import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
namespace std::io::cursor;Cursor: an in-memory byte buffer that is Read, Write, and Seek.
mut name: Type = value;A mutable binding, reassignable after declaration - mutability is opt-in, const is the default. At module level it declares mutable global state. Before & it marks an exclusive reference or receiver instead.
mut c: Cursorstatic Cursor::empty() -> CursorA cursor over a fresh empty buffer - the usual starting point for accumulating bytes with write.
mut c: CursorCursor::write<T>(mut &this, data: T) -> Result<(), IoError>via trait Write
Write data in full, retrying short writes and Interrupted errors. Generic over the payload, dispatched at compile time via static match: a raw byte Slice<u8>, a Str view, a NUL-terminated C string, or a single u8.
mut bytes: Array<u8>Cursor::into_inner(mut &this) -> Array<u8>Move the buffer out, leaving the cursor holding a fresh empty buffer. The typical "collect the written bytes" finisher; the cursor stays valid and must still be dropped.
std::io::cursortype trait Read {
read(mut &this, buffer: u8*, length: u64) -> Result<u64, IoError>;
read_all(mut &this, buffer: u8*, length: u64) -> Result<u64, IoError>;
read_byte(mut &this) -> Result<Option<u8>, IoError>;
read_char(mut &this) -> Result<Option<u32>, IoError>;
read_until(mut &this, delimiter: u8, out: mut &Array<u8>) -> Result<u64, IoError>;
read_exact(mut &this, buffer: u8*, length: u64) -> Result<(), IoError>;
read_to_end(mut &this, out: mut &Array<u8>) -> Result<u64, IoError>;
read_to_string(mut &this, out: mut &String) -> Result<u64, IoError>;
read_line(mut &this, out: mut &String) -> Result<u64, IoError>;
}type trait Write {
write_some(mut &this, bytes: Slice<u8>) -> Result<u64, IoError>;
flush(mut &this) -> Result<(), IoError>;
write<T>(mut &this, data: T) -> Result<(), IoError>;
}type trait Seek {
seek(mut &this, from: SeekFrom) -> Result<u64, IoError>;
stream_position(mut &this) -> Result<u64, IoError>;
rewind(mut &this) -> Result<(), IoError>;
}A byte stream whose read/write cursor can be repositioned. Absolute positions are u64 offsets from the start; every seek returns the resulting absolute position.
static Cursor::new(buffer: Array<u8>) -> CursorWrap an existing byte buffer with the cursor at position 0. Takes ownership of buffer; reads start at its first byte.
Cursor.buffer: Array<u8>IoErrorKind::WriteZeroCursor.pos: u64Cursor::position(&this) -> u64Current cursor position: the absolute byte offset from the start where the next read or write lands. Independent of the buffer length; may exceed it after a seek-past-end.
std::io::cursorCursor::set_position(mut &this, pos: u64) -> voidSet the cursor position directly. Positions past the buffer end are allowed and behave as documented on the type.
std::io::cursorCursor::len(&this) -> u64Number of bytes currently in the buffer, independent of the cursor position.
std::io::cursorCursor::as_bytes(&this) -> Slice<u8>Borrow the buffered bytes without moving the cursor. The slice is invalidated by any subsequent write (which may reallocate).
std::io::cursorimplement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.
implement trait Trait for Type { ... }Introduces a trait implementation: the block supplies, for one concrete type, the method bodies the trait requires.
language referenceimplement trait Trait for Type { ... }Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.
language reference