Memory Domain API Guidelines

Core Semantics

borrowed view = non-owning contiguous bytes valid until source mutation or destruction
direct owner = independent allocation copied deeply and transferred by move
shared block = immutable value or slice sharing read-only allocation ownership
block editor = mutable copy-on-write value that detaches before modification
marked allocation = one-way marker that is passed to all copies of an object.
secure erasure = optimizer-resistant overwrite of complete owned capacity
constant-time equality = explicit comparison without content-dependent short-circuiting for equal lengths

Primary Types

Byte // explicit single-byte value
ByteSpan, ConstByteSpan // mutable and read-only dynamic byte views
FixedByteSpan❮extent❯, FixedConstByteSpan❮extent❯ // fixed-extent byte views
ByteArray❮size❯ // fixed-size mutable byte owner
ByteBuffer // dynamic deep-copying mutable byte owner
ByteBlock // shared read-only byte value and slice

Secondary Types

Endianness // little- or big-endian integer byte order
ByteIntegerFormat // explicit signed or unsigned static/variable integer wire format
ByteTextFormat, ByteTextOptions // dynamic or padded text framing definition
ByteBlockEditor // explicit mutable copy-on-write byte value
RingBuffer, ByteRingBuffer // bounded FIFO bytes with optional integer operations
BitReader // sequential single-bit reader over borrowed read-only bytes
ByteReader, ByteWriter // sequential byte and integer reader and writer
StorageIdentifier // identity token for a visible backend storage range
CowStorage❮Data❯, CowManualStorage❮Data❯ // automatic- and explicit-detach copy-on-write wrappers
SharedData, SharedVirtualData // intrusive shared-data bases
SharedArrayData❮Value❯ // intrusive trailing-array storage
SharedDataPointer❮Data❯ // intrusive shared-data pointer with optional manual detach
ReferenceCounter // atomic intrusive reference state
UnsafeConstMemoryPtr, UnsafeMemoryPtr // explicit raw memory boundaries
UnsafeConstCharPtr, UnsafeCharPtr // explicit raw character boundaries

Compression Types

ByteCompressionAlgorithm // stable raw compression algorithm identifier and output bound
ByteCompressor, ByteDecompressor // one-shot and buffered byte compression
ByteCompressionError, ByteCompressionErrorReason // malformed or unsupported representation failure

Pattern Definitions

B = ByteArray❮size❯/ByteBuffer/ByteBlock/ByteBlockEditor // owning byte sequence
S = ByteSpan/ConstByteSpan/FixedByteSpan❮size❯/FixedConstByteSpan❮size❯ // borrowed byte sequence

Internal Byte Tool Patterns

o.dataView() -> impl::ByteDataView // private raw view shared by contiguous byte owners
byteReadTools(view) // bind ByteReadTools for read, iteration, conversion, slicing, and integer algorithms
byteComparisonTools(view) // bind ByteComparisonTools for comparison and search algorithms
o.writableSpan() -> ByteSpan // private fixed-size mutation boundary for writable owners
byteWriteTools(span) // bind ByteWriteTools for raw set, fill, overwrite, XOR, and integer writes
byteModifyTools(owner) // bind ByteModifyTools for COW, aliasing, sensitivity, allocation, and resizing
operationalTools(dataOrService) // bind operational tools to the data or service they operate on
staticHelper(...) // allow static helpers only as subordinate details of a stateful tool
o.validateWrite(...) // reject ineffective writes before requesting a span that can detach or reallocate
algorithm(view) // do not repeatedly traverse shared storage or create another owning byte object

Byte Value Patterns

T(value) // create from a raw byte-compatible value
o.toStdByte()/toUInt8()/toChar() -> T // cross an explicit raw-value boundary
o.shifted❮Direction❯/rotated❮Direction❯(amount) -> Byte // return transformed bits
o.shift❮Direction❯/rotate❮Direction❯(amount) // transform bits in place
o.masked(mask) -> Byte // return masked bits
o.matches(mask, expected) -> bool // test masked bits against an expected value

Byte Sequence Read Patterns

o.isEmpty() -> bool // test for no visible bytes
o.length()/endIndex() -> T // inspect visible sequence bounds
o.get(index[, fallback]) -> Byte // tolerant indexed access
o.getOrThrow(index) -> Byte // strict indexed access
o.span([range]) -> ConstByteSpan // borrow complete or clamped visible bytes
o.isEqualConstTime(bytes) -> bool // compare every byte when lengths match; lengths remain observable
o.startsWith/endsWith/contains(bytes) -> bool // test byte-sequence membership
o.find/findLast(bytes[, start]) -> unit::ByteIndex // locate a byte sequence
o.forEach(function) -> util::LoopResult // visit bytes with an optional index
o.toByteBuffer() -> ByteBuffer // create an independent mutable byte copy

Mutable Byte Sequence Patterns

T(length[, value])/T(bytes) // create owned byte storage
T::fromSpan(span) -> T // explicitly copy borrowed bytes for dynamic owners
T::fromSpan(span) -> std::optional❮T❯ // copy exact-size bytes into a fixed array, or reject a mismatch
T::fromSpanOrThrow(span) -> T // strictly copy an exactly sized borrowed sequence into a fixed array
o.set/setOrThrow(index, byte) // tolerant or strict indexed write
o.fill([range], byte) // fill complete or clamped visible storage
o.overwrite([range], bytes) // copy the largest fitting source prefix without resizing
o.xorAt/xorAtOrThrow(index, byte) // tolerant or strict indexed XOR
o.xorWith([range], bytes) -> T // apply bulk XOR with type-specific size behavior
o.xorWithOrThrow(bytes) -> T // require equal lengths for whole-sequence XOR
o.append/insert/replace(position, bytes) -> T& // resize and add or replace bytes
o.remove/keep(range) -> T& // remove or retain a clamped range
o.resize/reserve/shrinkToFit(capacity) // manage visible length and capacity
o.clear()/reset() // empty while retaining or releasing storage

Shared Block Patterns

T(editor-or-block) // share visible block allocation ownership
o.copy() -> T // create independent storage with only the visible bytes
o.slice(range) -> ByteBlock // create a shared read-only slice
o.kept(range) -> T // create independent storage with only a clamped visible range
o.join(parts) -> ByteBlockEditor // join byte sequences using the receiver as separator
T::fromJoined(parts) -> ByteBlockEditor // join byte sequences without a separator
o.detach() // ensure unique mutable storage before low-level access

Integer Access Patterns

getInteger❮T❯(bytes, offset[, endianness, fallback]) -> T // tolerant endian-aware read
getIntegerInto(bytes, value, offset[, endianness]) -> bool // checked endian-aware read
getIntegerOrThrow❮T❯(bytes, offset[, endianness]) -> T // strict endian-aware read
setInteger(bytes, offset, value[, endianness]) -> bool // checked endian-aware write
setIntegerOrThrow(bytes, offset, value[, endianness]) // strict endian-aware write
toByteSpan/toConstByteSpan(stdSpan) -> S // create a zero-copy compatibility view

Sequential Read and Write Patterns

T(block-or-editor) // create a reader sharing its input data
T([endianness]) // create an empty sequential writer
o.position()/length() -> T // inspect sequential bounds
o.isAtEnd() -> bool // test whether a sequential reader reached its end
o.setPosition/advance(amount) // move within clamped bounds
o.readByte/peekByte([fallback]) -> Byte // tolerant advancing or non-advancing read
o.readByteOrThrow/peekByteOrThrow() -> Byte // strict advancing or non-advancing read
o.readInteger❮T❯([fallback])/readIntegerOrThrow❮T❯() -> T // compatibility native-width integer read
o.readInteger❮T❯(format) -> optional❮T❯ // transactional formatted integer read
o.readIntegerOrThrow❮T❯(format) -> T // strict formatted integer read
o.readBytes(length) -> optional❮ByteBlock❯ // transactional exact byte read
o.readBytesOrThrow(length) -> ByteBlock // strict exact byte read
o.readText(options) -> optional❮String❯ // transactional structured text read
o.readTextOrThrow(options) -> String // strict structured text read
o.writeByte/writeInteger(value)/writeIntegerOrThrow(value, format) -> ByteWriter& // append and advance
o.writeText(text, options)/writeTextOrThrow(text, options) -> ByteWriter& // truncating or strict text frame
o.toByteBlock() -> ByteBlock // materialize written bytes

Ring Buffer Patterns

T(capacity[, maximumCapacity]) // create a fixed or growable bounded ring
o.length()/available()/capacity()/maximumCapacity() -> unit::ByteLength // inspect ring bounds
o.write(bytes)/read(destination) -> unit::ByteLength // transfer as many bytes as possible
o.writeExact(bytes) -> util::Result // atomically write all bytes or leave the ring unchanged
o.read(maximum) -> ByteBlock // remove up to the requested byte count
o.readInteger() -> T // atomically read one endian-aware integer
o.writeInteger(value) -> util::Result // atomically write one endian-aware integer
o.clear()/shrinkToInitial() // discard bytes or restore empty initial capacity

Byte Compression Patterns

T(algorithm) // create a raw compressor or decompressor for one algorithm
o.compress(bytes)/decompress(bytes, originalSize) -> ByteBlock // transform a raw algorithm block
o.compressWithEnvelope(bytes) -> ByteBlock // create a framed self-describing representation
T::decompressWithEnvelope(bytes[, maximumSize]) -> ByteBlock // validate, dispatch, and decode an envelope
o.update(bytes) // append buffered incremental input before finalization
o.finalize([originalSize])/finalizeWithEnvelope([maximumSize]) -> ByteBlock // finalize in one selected format
o.reset() // discard buffered input and cached output for reuse

Sensitive Byte Storage Patterns

o.isSensitive() -> bool // inspect the shared-allocation mark or direct-owner mode
o.markAsSensitive() // irreversibly mark ByteBlock or ByteBlockEditor shared storage
o.setSensitive(enabled) // configure reversible ByteBuffer or RingBuffer sensitive mode
o.secureErase() // erase complete capacity while preserving visible length and sensitivity
o.copy/slice/mutate(...) -> T // preserve or propagate sensitivity according to owning-type semantics

Shared Storage Patterns

T::create/from(data) -> T // create unique shared storage
o.data()/detachedData() -> T& // access data with automatic or explicit detach semantics
o.setData/emplaceData(value) // replace storage with a unique object
o.detach() // ensure unique shared storage
o.isShared()/useCount() -> T // inspect shared ownership
o.reset([data])/swap(other) // replace or exchange intrusive storage