Expand description
A rope-like byte sequence with O(log n) append, prepend and slicing, O(1) cloning, and a 16 byte footprint with 15 bytes of inline storage.
§When to use a Cord
A Cord is designed for large byte sequences that change over their
lifetime or are shared across API boundaries: wire-format messages that
get headers prepended or payloads appended, buffers assembled from many
pieces, or data that is sliced and passed around without copying. For
small, contiguous, rarely modified data prefer Vec<u8> or
bytes::Bytes.
§Example
use cord_rs::{Cord, CordBuffer};
// Small values live inline; no allocation.
let mut cord = Cord::from("hello");
assert_eq!(cord.len(), 5);
// Append and prepend from byte- and string-like sources.
cord.append(" world");
cord.prepend(">> ");
// This small slice is copied inline; larger slices share backing storage.
let world = cord.slice(9..);
assert_eq!(world, "world");
// Large owned buffers are adopted rather than copied.
cord.append(vec![b'!'; 4096]);
assert_eq!(cord.len(), 3 + 11 + 4096);
// Zero-copy building through `CordBuffer`.
let mut buffer = CordBuffer::with_capacity(32);
buffer.put_slice(b" tail");
cord.append(buffer);
// Iterate chunks for efficient processing, or bytes for convenience.
let total: usize = cord.chunks().map(<[u8]>::len).sum();
assert_eq!(total, cord.len());
assert!(cord.ends_with(" tail"));§Representation
A Cord is 16 bytes: either up to 15 bytes of inline data, or a pointer
to a reference counted tree. Trees are B-trees of up to 6 edges per node
whose leaves reference immutable flat buffers (allocated in size classes
from 32 bytes to 4 KiB by default, or up to 64 KiB when built through
CordBuffer::with_capacity_and_block_size, see its docs for the sizing
trade-offs), external buffers owned by user values (Vec<u8>,
Arc<[u8]>, custom Cord::from_owner values, …), or substrings of
those. Buffers referenced by a single cord are grown in place; buffers
shared between cords are never modified.
§Features
std(default) —std::iointegration:Read/BufRead/SeekonCursor, andWriteonCordandCordBuffer. Building withdefault-features = falsegives a crate usingno_stdandalloc(with any global allocator); everything else — includingcore::fmt::WriteforCord— stays available.no_stdtargets need 32-bit and pointer-width atomics (target_has_atomic = "32"and"ptr").bytes—bytes::BufforCordandCursor,bytes::BufMutforCordWriterandCordBuffer, and zero-copy conversions withbytes::Bytes. With bothbytesandstdenabled,CordWriteralso implementsstd::io::Write.serde—Serialize/DeserializeforCordas a byte sequence.
Modules§
- iter
- Iterators over the contents of a
Cord:Chunksyields contiguous byte slices,Bytesyields individual bytes, andCursoris a positioned reader supporting skipping and seeking,std::io::Read/Seek, and cheap sub-cord extraction. Not re-exported at the crate root —BytesandCursorwould collide withbytes::Bytesandstd::io::Cursor, so (likestr::Bytes,slice::Chunksandio::Cursorinstd) they stay reachable through this module.
Structs§
- Cord
- A rope-like sequence of bytes with cheap append, prepend, slicing and cloning.
- Cord
Buffer - A buffer of bytes that can be appended to (or prepended to) a
Cordwithout copying. - Cord
Writer bytes - A
BufMut(and, with thestdfeature,std::io::Write) adapter that appends to aCordthroughCordBuffers, so that data can be written into uninitialized memory that becomes part of the cord without copying.
Enums§
- Memory
Accounting - Memory accounting modes for
Cord::estimated_memory_usage.
Traits§
- Cord
Index - Types usable as an index in
Cord::get:usize(yielding a byte) and the range types (yielding a sub-cord). Sealed. - Cord
Like - Byte sequences a
Cordcan be compared with and searched for:Cord,[u8],str,Vec<u8>,String,[u8; N],CordBufferand references to those. - Cord
Source - Types that can be appended to or prepended to a
CordviaCord::append/Cord::prepend.