Skip to main content

Crate cord_rs

Crate cord_rs 

Source
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::io integration: Read/BufRead/Seek on Cursor, and Write on Cord and CordBuffer. Building with default-features = false gives a crate using no_std and alloc (with any global allocator); everything else — including core::fmt::Write for Cord — stays available. no_std targets need 32-bit and pointer-width atomics (target_has_atomic = "32" and "ptr").
  • bytes — bytes::Buf for Cord and Cursor, bytes::BufMut for CordWriter and CordBuffer, and zero-copy conversions with bytes::Bytes. With both bytes and std enabled, CordWriter also implements std::io::Write.
  • serde — Serialize / Deserialize for Cord as a byte sequence.

Modules§

iter
Iterators over the contents of a Cord: Chunks yields contiguous byte slices, Bytes yields individual bytes, and Cursor is a positioned reader supporting skipping and seeking, std::io::Read/ Seek, and cheap sub-cord extraction. Not re-exported at the crate root — Bytes and Cursor would collide with bytes::Bytes and std::io::Cursor, so (like str::Bytes, slice::Chunks and io::Cursor in std) they stay reachable through this module.

Structs§

Cord
A rope-like sequence of bytes with cheap append, prepend, slicing and cloning.
CordBuffer
A buffer of bytes that can be appended to (or prepended to) a Cord without copying.
CordWriterbytes
A BufMut (and, with the std feature, std::io::Write) adapter that appends to a Cord through CordBuffers, so that data can be written into uninitialized memory that becomes part of the cord without copying.

Enums§

MemoryAccounting
Memory accounting modes for Cord::estimated_memory_usage.

Traits§

CordIndex
Types usable as an index in Cord::get: usize (yielding a byte) and the range types (yielding a sub-cord). Sealed.
CordLike
Byte sequences a Cord can be compared with and searched for: Cord, [u8], str, Vec<u8>, String, [u8; N], CordBuffer and references to those.
CordSource
Types that can be appended to or prepended to a Cord via Cord::append / Cord::prepend.