docs.phext.io
LATEST REFERENCE
Reference as of head commit 84c10399cccc8e5f34b2aadcade96907b5b1a655 · 83 commits audited · chain sha256 8857d4baa3c5ac59…

libphext-rs — project documentation

Scanned by phdoc 0.1.0 on 2026-11-22 (Exocortical Epoch 95). Project root: /home/wbic16/phdoc-sweep/proj/libphext-rs/. Scanned at commit 84c10399cccc8e5f34b2aadcade96907b5b1a655. Every fact in this document was read from its own records: its manifests, its git log, and its source text. Nothing here was guessed.

This document holds: what the project depends on, who wrote it, how large and how complex it is, the state of its quality signals, the RFCs it declares, where its upstream repo lives, and a plain English note for every public method and command.


Dependencies

Rust (cargo) — Cargo.toml

License stated in the manifest: MIT.

Direct dependencies: 3.

Rust (cargo) — counter/Cargo.toml

Direct dependencies: 0.

Rust (cargo) — counter/kernel/Cargo.toml

Direct dependencies: 0.


Authors

The git log holds 83 commits.

The author of record is Will Bickford — 83 commits folded into his account. Will's ruling (2026-11-22): all Exocortical authors fold into his account — "I speak for the cluster." The fold is presentation only: the git history is unchanged, and the per-persona detail is kept as annotation.

Annotation, by persona (all folded into Will Bickford):


Complexity

The measure is stated plainly, and no single score is made: lines are counted per file as total lines, blank lines, comment lines, and code lines (total minus blank minus comment). Functions are counted where the scanner reads them, and the largest functions are given by their span in lines.

All languages: 64 files, 10774 lines total, 7611 lines of code. Functions read: 335.

Largest files:

Largest functions, by span in lines:


Code quality signals

Each signal is named and shown with its evidence. A signal is a fact the scanner read, not a grade.


Declared RFCs

No rfcs.json was found in this project, so it declares no RFCs. This is a finding, not an error: the project has not made an RFC declaration.


Upstream git repo


Public methods and commands

Every public method and command the scanner found, each with a plain English note. A note says where its words came from: the code's own doc comment, the item's signature, the user's agent, or it is marked awaiting a summary.


struct — State

Found in counter/kernel/src/lib.rs at line 8.

Signature: pub struct State {

What it does: The whole state: a counter that must never pass its limit.

(Where these words came from: doc comment.)


enum — Command

Found in counter/kernel/src/lib.rs at line 14.

Signature: pub enum Command {

What it does: A named choice named Command. It is one of: Incr; Reset.

(Where these words came from: signature.)


enum — Error

Found in counter/kernel/src/lib.rs at line 22.

Signature: pub enum Error {

What it does: A named choice named Error. It is one of: AtLimit.

(Where these words came from: signature.)


function — transition

Found in counter/kernel/src/lib.rs at line 27.

Signature: pub fn transition(s: &State, cmd: &Command) -> Result<State, Error> {

What it does: One step: the next state, or why the command is refused.

(Where these words came from: doc comment.)


entry point — main

Found in examples/explode_bench.rs at line 11.

Signature: fn main() {

What it does: The entry point: the program starts here. It reads the command line and runs the command the user named.

(Where these words came from: signature.)


const — BINARY_SCROLL_HEADER

Found in src/binary.rs at line 42.

Signature: pub const BINARY_SCROLL_HEADER: &str = "phext-binary:1:base64";

What it does: The first (and only header) line of a binary scroll, without its line break.

(Where these words came from: doc comment.)


function — is_binary_scroll

Found in src/binary.rs at line 53.

Signature: pub fn is_binary_scroll(scroll: &str) -> bool {

What it does: ---------------------------------------------------------------------------------------------------------- @fn is_binary_scroll true when scroll carries the binary scroll header. Decoding success is a separate question — see decode_scroll. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — encode_scroll

Found in src/binary.rs at line 62.

Signature: pub fn encode_scroll(payload: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn encode_scroll encodes raw bytes as a binary scroll (header line + base64 body) ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — decode_scroll

Found in src/binary.rs at line 75.

Signature: pub fn decode_scroll(scroll: &str) -> Option<Vec<u8>> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn decode_scroll decodes a binary scroll back to its raw bytes. Returns None when the scroll is not a binary scroll, or when its body is not strict base64. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — insert_binary

Found in src/binary.rs at line 87.

Signature: pub fn insert_binary(input: String, location: Coordinate, payload: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn insert_binary stores payload at location as a binary scroll, unconditionally: the caller has declared this scroll binary, even if the bytes happen to be valid UTF-8. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — replace_binary

Found in src/binary.rs at line 97.

Signature: pub fn replace_binary(input: &str, location: Coordinate, payload: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn replace_binary replaces the scroll at location with payload, stored as a binary scroll (see insert_binary). ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — fetch_binary

Found in src/binary.rs at line 110.

Signature: pub fn fetch_binary(input: &str, target: Coordinate) -> Vec<u8> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn fetch_binary retrieves the bytes held at target. A well-formed binary scroll decodes to its payload. Any other scroll — plain text, a malformed binary scroll, or no scroll at all — yields the scroll's own UTF-8 bytes (empty when the coordinate is unoccupied), mirroring how phext::fetch returns "" there. This function is total: it never panics and never loses scroll content. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — insert_bytes

Found in src/binary.rs at line 134.

Signature: pub fn insert_bytes(input: String, location: Coordinate, payload: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn insert_bytes byte-oriented insert: stores payload at location under the ingestion rule (UTF-8 as text, non-UTF-8 as a base64-verbatim binary scroll). ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — replace_bytes

Found in src/binary.rs at line 144.

Signature: pub fn replace_bytes(input: &str, location: Coordinate, payload: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn replace_bytes byte-oriented replace: stores payload at location under the ingestion rule (UTF-8 as text, non-UTF-8 as a base64-verbatim binary scroll). ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — phokenize_bytes

Found in src/binary.rs at line 180.

Signature: pub fn phokenize_bytes(input: &[u8]) -> Vec<(Coordinate, Vec<u8>)> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn phokenize_bytes the byte-level twin of phext::phokenize: walks a raw byte stream and returns each scroll's coordinate and raw bytes, with identical segmentation. Dimension-break bytes are ASCII, so byte offsets are exact; scroll bodies are returned uninterpreted, valid UTF-8 or not. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — ingest

Found in src/binary.rs at line 227.

Signature: pub fn ingest(bytes: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn ingest ingests an externally supplied phext byte stream. Every scroll is observed as raw bytes: valid UTF-8 scrolls pass through verbatim, and any scroll whose bytes are not valid UTF-8 is stored as a binary scroll holding the base64 of the exact observed bytes (the ingestion rule), so fetch_binary at its coordinate returns the original bytes exactly. Never rejects, never panics. The result is the canonical serialization (the same normal form as phext::implode of phext::explode). ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


const — FIELD_PREFIX

Found in src/binary.rs at line 243.

Signature: pub const FIELD_PREFIX: &str = "phext-field:base64:";

What it does: The prefix of a binary field: arbitrary bytes encoded for one line inside a text scroll (a name=value grammar, a WAL entry, a header block). Whole scrolls use encode_scroll; fields use this.

(Where these words came from: doc comment.)


function — encode_field

Found in src/binary.rs at line 255.

Signature: pub fn encode_field(payload: &[u8]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn encode_field Encodes raw bytes as a single line of text: the field prefix plus RFC 4648 base64. The result contains no line breaks and none of the nine phext dimension-break bytes, so it can sit inside any line-structured scroll. The base64 overhead (+33%) is inherent to armouring bytes in a text line; this function standardizes the armour so every implementation reads the same field the same way. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — decode_field

Found in src/binary.rs at line 269.

Signature: pub fn decode_field(text: &str) -> Option<Vec<u8>> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn decode_field Decodes a field produced by encode_field. Returns None when the text lacks the field prefix or its body is not strict base64 — a plain text field is not a binary field, and yields None, not bytes. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


const — EPOCH_ANCHOR_UNIX

Found in src/epoch.rs at line 58.

Signature: pub const EPOCH_ANCHOR_UNIX: i64 = 1795327200;

What it does: The unix timestamp at which EE 1 begins: 2026-11-22T06:00:00Z.

(Where these words came from: doc comment.)


const — EPOCH_LENGTH_SECONDS

Found in src/epoch.rs at line 61.

Signature: pub const EPOCH_LENGTH_SECONDS: i64 = 420;

What it does: The length of one Exocortical Epoch, in seconds (7 minutes).

(Where these words came from: doc comment.)


const — AGE_BITS

Found in src/epoch.rs at line 65.

Signature: pub const AGE_BITS: u32 = 42;

What it does: The width of a Sentron Age field, in bits: one epoch is divided into 2^42 Sentron Ages.

(Where these words came from: doc comment.)


const — AGES_PER_EPOCH

Found in src/epoch.rs at line 71.

Signature: pub const AGES_PER_EPOCH: u64 = 1 << AGE_BITS;

What it does: The number of Sentron Ages in one Exocortical Epoch: 2^42 = 4,398,046,511,104. The canonical reference clock is AGES_PER_EPOCH / 420 ≈ 10.4715 GHz, so one Sentron Age is ≈ 95.5 picoseconds.

(Where these words came from: doc comment.)


const — AGE_MAX

Found in src/epoch.rs at line 74.

Signature: pub const AGE_MAX: u64 = AGES_PER_EPOCH - 1;

What it does: The largest Sentron Age: the final nominal step of an epoch.

(Where these words came from: doc comment.)


const — COARSE_AGE_BITS

Found in src/epoch.rs at line 80.

Signature: pub const COARSE_AGE_BITS: u32 = 16;

What it does: The width of a coarse Sentron Age field, in bits: the fine Sentron Age scaled into a 16-bit address space (coarse = fine >> (AGE_BITS − COARSE_AGE_BITS)). One coarse tick is 420 / 65536 s ≈ 6.41 ms.

(Where these words came from: doc comment.)


const — COARSE_AGES_PER_EPOCH

Found in src/epoch.rs at line 84.

Signature: pub const COARSE_AGES_PER_EPOCH: u64 = 1 << COARSE_AGE_BITS;

What it does: The number of coarse Sentron Ages in one Exocortical Epoch: 2^16 = 65,536.

(Where these words came from: doc comment.)


const — COARSE_AGE_MAX

Found in src/epoch.rs at line 87.

Signature: pub const COARSE_AGE_MAX: u64 = COARSE_AGES_PER_EPOCH - 1;

What it does: The largest coarse Sentron Age: the final coarse step of an epoch.

(Where these words came from: doc comment.)


function — epoch_at

Found in src/epoch.rs at line 97.

Signature: pub fn epoch_at(unix_seconds: i64) -> u64 {

What it does: ---------------------------------------------------------------------------------------------------------- @fn epoch_at the Exocortical Epoch containing the given unix timestamp (UTC seconds). Returns 0 for every instant before the anchor — EE 0, the pre-epoch. For instants at or after the anchor this is floor((t − anchor) / 420) + 1, computed in 64-bit arithmetic. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — epoch_start

Found in src/epoch.rs at line 111.

Signature: pub fn epoch_start(epoch: u64) -> Option<i64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn epoch_start the unix timestamp at which the given epoch begins. None for EE 0 — the pre-epoch has no start — and None for epoch numbers so large that the start is not representable as an i64 unix timestamp. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — epoch_end

Found in src/epoch.rs at line 126.

Signature: pub fn epoch_end(epoch: u64) -> Option<i64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn epoch_end the unix timestamp at which the given epoch ends — the next epoch's start. None for EE 0, and None when the end is not representable as an i64 unix timestamp. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — epoch_range

Found in src/epoch.rs at line 137.

Signature: pub fn epoch_range(epoch: u64) -> Option<(i64, i64)> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn epoch_range the (start, end) unix timestamps bounding the given epoch. None for EE 0 — all of history before the anchor is not an interval this clock bounds — and None when either bound is not representable as i64. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — seconds_into_epoch

Found in src/epoch.rs at line 148.

Signature: pub fn seconds_into_epoch(unix_seconds: i64) -> Option<i64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn seconds_into_epoch how far the given unix timestamp sits inside its epoch, in seconds (0 at an epoch's first instant, 419 at its last). None before the anchor: a pre-epoch instant is not inside any epoch. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — seconds_remaining

Found in src/epoch.rs at line 163.

Signature: pub fn seconds_remaining(unix_seconds: i64) -> i64 {

What it does: ---------------------------------------------------------------------------------------------------------- @fn seconds_remaining seconds until the current epoch ends. Before the anchor this counts down to the start of EE 1 (at the anchor itself it reads 420 — the full first epoch lies ahead); at or after the anchor it is the time left in the containing epoch, in the range 1..=420. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — age_at

Found in src/epoch.rs at line 186.

Signature: pub fn age_at(unix_seconds: i64) -> Option<u64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn age_at the Sentron Age of the given unix timestamp: its nominal position within its epoch, floor(seconds_into_epoch × 2^42 / 420), in the range 0..=AGE_MAX. None before the anchor, exactly as seconds_into_epoch — a pre-epoch instant is inside no epoch, so it has no Sentron Age. Whole-second input fixes the Sentron Age at that second's first instant; age_at_nanos refines it with the sub-second part. A Sentron Age is a local position: 1 ms of clock skew moves it by ≈ 10.47 million Sentron Ages, so Sentron Ages order events on one clock — the epoch count is the coordinate that travels between machines. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — age_at_nanos

Found in src/epoch.rs at line 204.

Signature: pub fn age_at_nanos(unix_seconds: i64, nanoseconds: u32) -> Option<u64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn age_at_nanos the Sentron Age of a timestamp given with sub-second precision: unix_seconds plus nanoseconds (0..1_000_000_000) within that second. The Sentron Age is floor(elapsed_ns × 2^42 / (420 × 10^9)) over the nanoseconds elapsed in the containing epoch, computed in 128-bit arithmetic (elapsed_ns × 2^42 overflows u64). None before the anchor, and None for an out-of-range nanosecond part. With nanoseconds == 0 the result agrees exactly with age_at. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — age_start

Found in src/epoch.rs at line 231.

Signature: pub fn age_start(epoch: u64, age: u64) -> Option<i64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn age_start the unix timestamp of the whole second in which the given Sentron Age of the given epoch begins: epoch_start(epoch) + floor(age × 420 / 2^42). None for EE 0, for age > AGE_MAX, and when that second is not representable as an i64 unix timestamp. This is the coarsest faithful inverse of age_at, and its coarseness is the module's honesty about resolution: a Sentron Age is ≈ 95.5 ps wide, so ~10.47 billion Sentron Ages begin inside each second and no whole-second timestamp can name one Sentron Age's exact start. The inverse therefore names the containing second — expect it to read one second early when the Sentron Age in force at a second boundary began just before it. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — coarse_age_at

Found in src/epoch.rs at line 257.

Signature: pub fn coarse_age_at(unix_seconds: i64) -> Option<u64> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn coarse_age_at the coarse Sentron Age of the given unix timestamp: the fine Sentron Age scaled into a 16-bit address space, age_at(t) >> 26, equivalently floor(seconds_into_epoch × 65536 / 420), in the range 0..=COARSE_AGE_MAX. None before the anchor, exactly as age_at. This is the register-grade form. One coarse tick is ≈ 6.41 ms, so where a fine Sentron Age (≈ 95.5 ps) is destroyed by any real clock skew — 1 ms is ≈ 10.47 million fine Sentron Ages — NTP-class skew of a few milliseconds costs a coarse Sentron Age about a tick. Coarse Sentron Ages are therefore approximately comparable across machines, and they are the Age component the register system carries. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


const — COORDINATE_MINIMUM

Found in src/phext.rs at line 86.

Signature: pub const COORDINATE_MINIMUM: usize = 1; // human numbering - we start at 1, not 0

What it does: ---------------------------------------------------------------------------------------------------------- phext constants ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


const — LIBRARY_BREAK

Found in src/phext.rs at line 89.

Signature: pub const LIBRARY_BREAK: char = '\x01'; // 11th dimension - replaces start of header

What it does: A fixed value named LIBRARY_BREAK, set to '\x01'; // 11th dimension - replaces start of header.

(Where these words came from: signature.)


const — CHAIN_BREAK

Found in src/phext.rs at line 90.

Signature: pub const CHAIN_BREAK: char = '\x02'; // stream level - separates whole phexts within a chain; replaces start of text

What it does: A fixed value named CHAIN_BREAK, set to '\x02'; // stream level - separates whole phexts within a ch.

(Where these words came from: signature.)


const — CHAIN_CLOSE

Found in src/phext.rs at line 91.

Signature: pub const CHAIN_CLOSE: char = '\x03'; // stream level - terminates a chain; replaces end of text

What it does: A fixed value named CHAIN_CLOSE, set to '\x03'; // stream level - terminates a chain; replaces end o.

(Where these words came from: signature.)


const — MORE_COWBELL

Found in src/phext.rs at line 92.

Signature: pub const MORE_COWBELL: char = '\x07'; // i've got a fever, and the only prescription...is more cowbell!

What it does: A fixed value named MORE_COWBELL, set to '\x07'; // i've got a fever, and the only prescription...is .

(Where these words came from: signature.)


const — LINE_BREAK

Found in src/phext.rs at line 93.

Signature: pub const LINE_BREAK: char = '\x0A'; // same as plain text \o/

What it does: A fixed value named LINE_BREAK, set to '\x0A'; // same as plain text \o/.

(Where these words came from: signature.)


const — SCROLL_BREAK

Found in src/phext.rs at line 94.

Signature: pub const SCROLL_BREAK: char = '\x17'; // 3D Break - replaces End Transmission Block

What it does: A fixed value named SCROLL_BREAK, set to '\x17'; // 3D Break - replaces End Transmission Block.

(Where these words came from: signature.)


const — SECTION_BREAK

Found in src/phext.rs at line 95.

Signature: pub const SECTION_BREAK: char = '\x18'; // 4D Break - replaces Cancel Block

What it does: A fixed value named SECTION_BREAK, set to '\x18'; // 4D Break - replaces Cancel Block.

(Where these words came from: signature.)


const — CHAPTER_BREAK

Found in src/phext.rs at line 96.

Signature: pub const CHAPTER_BREAK: char = '\x19'; // 5D Break - replaces End of Tape

What it does: A fixed value named CHAPTER_BREAK, set to '\x19'; // 5D Break - replaces End of Tape.

(Where these words came from: signature.)


const — BOOK_BREAK

Found in src/phext.rs at line 97.

Signature: pub const BOOK_BREAK: char = '\x1A'; // 6D Break - replaces Substitute

What it does: A fixed value named BOOK_BREAK, set to '\x1A'; // 6D Break - replaces Substitute.

(Where these words came from: signature.)


const — VOLUME_BREAK

Found in src/phext.rs at line 98.

Signature: pub const VOLUME_BREAK: char = '\x1C'; // 7D Break - replaces file separator

What it does: A fixed value named VOLUME_BREAK, set to '\x1C'; // 7D Break - replaces file separator.

(Where these words came from: signature.)


const — COLLECTION_BREAK

Found in src/phext.rs at line 99.

Signature: pub const COLLECTION_BREAK: char = '\x1D'; // 8D Break - replaces group separator

What it does: A fixed value named COLLECTION_BREAK, set to '\x1D'; // 8D Break - replaces group separator.

(Where these words came from: signature.)


const — SERIES_BREAK

Found in src/phext.rs at line 100.

Signature: pub const SERIES_BREAK: char = '\x1E'; // 9D Break - replaces record separator

What it does: A fixed value named SERIES_BREAK, set to '\x1E'; // 9D Break - replaces record separator.

(Where these words came from: signature.)


const — SHELF_BREAK

Found in src/phext.rs at line 101.

Signature: pub const SHELF_BREAK: char = '\x1F'; // 10D Break - replaces unit separator

What it does: A fixed value named SHELF_BREAK, set to '\x1F'; // 10D Break - replaces unit separator.

(Where these words came from: signature.)


const — LIBRARY_BREAK_U8

Found in src/phext.rs at line 106.

Signature: pub const LIBRARY_BREAK_U8: u8 = 0x01; // byte form of LIBRARY_BREAK

What it does: A fixed value named LIBRARY_BREAK_U8, set to 0x01; // byte form of LIBRARY_BREAK.

(Where these words came from: signature.)


const — CHAIN_BREAK_U8

Found in src/phext.rs at line 107.

Signature: pub const CHAIN_BREAK_U8: u8 = 0x02; // byte form of CHAIN_BREAK

What it does: A fixed value named CHAIN_BREAK_U8, set to 0x02; // byte form of CHAIN_BREAK.

(Where these words came from: signature.)


const — CHAIN_CLOSE_U8

Found in src/phext.rs at line 108.

Signature: pub const CHAIN_CLOSE_U8: u8 = 0x03; // byte form of CHAIN_CLOSE

What it does: A fixed value named CHAIN_CLOSE_U8, set to 0x03; // byte form of CHAIN_CLOSE.

(Where these words came from: signature.)


const — MORE_COWBELL_U8

Found in src/phext.rs at line 109.

Signature: pub const MORE_COWBELL_U8: u8 = 0x07; // byte form of MORE_COWBELL

What it does: A fixed value named MORE_COWBELL_U8, set to 0x07; // byte form of MORE_COWBELL.

(Where these words came from: signature.)


const — LINE_BREAK_U8

Found in src/phext.rs at line 110.

Signature: pub const LINE_BREAK_U8: u8 = 0x0A; // byte form of LINE_BREAK

What it does: A fixed value named LINE_BREAK_U8, set to 0x0A; // byte form of LINE_BREAK.

(Where these words came from: signature.)


const — SCROLL_BREAK_U8

Found in src/phext.rs at line 111.

Signature: pub const SCROLL_BREAK_U8: u8 = 0x17; // byte form of SCROLL_BREAK

What it does: A fixed value named SCROLL_BREAK_U8, set to 0x17; // byte form of SCROLL_BREAK.

(Where these words came from: signature.)


const — SECTION_BREAK_U8

Found in src/phext.rs at line 112.

Signature: pub const SECTION_BREAK_U8: u8 = 0x18; // byte form of SECTION_BREAK

What it does: A fixed value named SECTION_BREAK_U8, set to 0x18; // byte form of SECTION_BREAK.

(Where these words came from: signature.)


const — CHAPTER_BREAK_U8

Found in src/phext.rs at line 113.

Signature: pub const CHAPTER_BREAK_U8: u8 = 0x19; // byte form of CHAPTER_BREAK

What it does: A fixed value named CHAPTER_BREAK_U8, set to 0x19; // byte form of CHAPTER_BREAK.

(Where these words came from: signature.)


const — BOOK_BREAK_U8

Found in src/phext.rs at line 114.

Signature: pub const BOOK_BREAK_U8: u8 = 0x1A; // byte form of BOOK_BREAK

What it does: A fixed value named BOOK_BREAK_U8, set to 0x1A; // byte form of BOOK_BREAK.

(Where these words came from: signature.)


const — VOLUME_BREAK_U8

Found in src/phext.rs at line 115.

Signature: pub const VOLUME_BREAK_U8: u8 = 0x1C; // byte form of VOLUME_BREAK

What it does: A fixed value named VOLUME_BREAK_U8, set to 0x1C; // byte form of VOLUME_BREAK.

(Where these words came from: signature.)


const — COLLECTION_BREAK_U8

Found in src/phext.rs at line 116.

Signature: pub const COLLECTION_BREAK_U8: u8 = 0x1D; // byte form of COLLECTION_BREAK

What it does: A fixed value named COLLECTION_BREAK_U8, set to 0x1D; // byte form of COLLECTION_BREAK.

(Where these words came from: signature.)


const — SERIES_BREAK_U8

Found in src/phext.rs at line 117.

Signature: pub const SERIES_BREAK_U8: u8 = 0x1E; // byte form of SERIES_BREAK

What it does: A fixed value named SERIES_BREAK_U8, set to 0x1E; // byte form of SERIES_BREAK.

(Where these words came from: signature.)


const — SHELF_BREAK_U8

Found in src/phext.rs at line 118.

Signature: pub const SHELF_BREAK_U8: u8 = 0x1F; // byte form of SHELF_BREAK

What it does: A fixed value named SHELF_BREAK_U8, set to 0x1F; // byte form of SHELF_BREAK.

(Where these words came from: signature.)


const — ADDRESS_MICRO_BREAK

Found in src/phext.rs at line 120.

Signature: pub const ADDRESS_MICRO_BREAK: u8 = b'.'; // delimiter for micro-coordinates

What it does: A fixed value named ADDRESS_MICRO_BREAK, set to b'.'; // delimiter for micro-coordinates.

(Where these words came from: signature.)


const — ADDRESS_MACRO_BREAK

Found in src/phext.rs at line 121.

Signature: pub const ADDRESS_MACRO_BREAK: u8 = b'/'; // delimiter for macro-coordinates

What it does: A fixed value named ADDRESS_MACRO_BREAK, set to b'/'; // delimiter for macro-coordinates.

(Where these words came from: signature.)


const — ADDRESS_MACRO_ALT

Found in src/phext.rs at line 122.

Signature: pub const ADDRESS_MACRO_ALT: u8 = b';'; // also allow ';' for url encoding

What it does: A fixed value named ADDRESS_MACRO_ALT, set to b';'; // also allow ';' for url encoding.

(Where these words came from: signature.)


struct — ZCoordinate

Found in src/phext.rs at line 169.

Signature: pub struct ZCoordinate {

What it does: ---------------------------------------------------------------------------------------------------------- @struct ZCoordinate The large-scale Z arm of a phext coordinate (see Coordinate below) ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — ZCoordinate::new

Found in src/phext.rs at line 175.

Signature: pub fn new() -> ZCoordinate {

What it does: Function ZCoordinate::new takes no inputs beyond the value it is called on, and gives back ZCoordinate.

(Where these words came from: signature.)


struct — YCoordinate

Found in src/phext.rs at line 196.

Signature: pub struct YCoordinate {

What it does: ---------------------------------------------------------------------------------------------------------- @struct YCoordinate The large-scale Y arm of a phext coordinate (see Coordinate below) ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — YCoordinate::new

Found in src/phext.rs at line 202.

Signature: pub fn new() -> YCoordinate {

What it does: Function YCoordinate::new takes no inputs beyond the value it is called on, and gives back YCoordinate.

(Where these words came from: signature.)


struct — XCoordinate

Found in src/phext.rs at line 223.

Signature: pub struct XCoordinate {

What it does: ---------------------------------------------------------------------------------------------------------- @struct XCoordinate The large-scale X arm of a phext coordinate (see Coordinate below) ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — XCoordinate::new

Found in src/phext.rs at line 229.

Signature: pub fn new() -> XCoordinate {

What it does: Function XCoordinate::new takes no inputs beyond the value it is called on, and gives back XCoordinate.

(Where these words came from: signature.)


struct — Coordinate

Found in src/phext.rs at line 264.

Signature: pub struct Coordinate {

What it does: ---------------------------------------------------------------------------------------------------------- @struct Coordinate provides access to a default-initialized coordinate at 1.1.1/1.1.1/1.1.1 phext coordinates are formed along a 9-dimensional hierarchy with three main arms of the form z3.z2.z1/y3.y2.y1.x3.x2.x1 where: Z - this arm contains the library (z3), shelf (z2), and series (z1) dimensions Y - this arm contains the collection (y3), volume (y2), and book (y1) dimensions X - this arm contains the chapter (x3), section (x2), and scroll (x1) dimensions Dense graphs: phext is sparse by design. Coordinate components are unbounded, but a fully-populated dense graph contains the product of its dimensions' extents in scrolls — a dense block spanning 1000 in each of 9 dimensions implies 10^27 scrolls. Materializing, exploding, or indexing such a graph costs memory proportional to its populated scroll count. The old 999 cap never protected against this (999^9 was already unreachable); sparsity does. Keep graphs sparse. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — Coordinate::new

Found in src/phext.rs at line 270.

Signature: pub fn new() -> Coordinate {

What it does: Function Coordinate::new takes no inputs beyond the value it is called on, and gives back Coordinate.

(Where these words came from: signature.)


struct — PositionedScroll

Found in src/phext.rs at line 281.

Signature: pub struct PositionedScroll {

What it does: A data shape named PositionedScroll. Its fields are: pub coord: Coordinate; pub scroll: String.

(Where these words came from: signature.)


function — PositionedScroll::new

Found in src/phext.rs at line 286.

Signature: pub fn new() -> PositionedScroll {

What it does: Function PositionedScroll::new takes no inputs beyond the value it is called on, and gives back PositionedScroll.

(Where these words came from: signature.)


struct — Range

Found in src/phext.rs at line 302.

Signature: pub struct Range {

What it does: A data shape named Range. Its fields are: pub start: Coordinate; pub end: Coordinate.

(Where these words came from: signature.)


function — Range::new

Found in src/phext.rs at line 307.

Signature: pub fn new() -> Range {

What it does: Function Range::new takes no inputs beyond the value it is called on, and gives back Range.

(Where these words came from: signature.)


struct — PhextParseError

Found in src/phext.rs at line 318.

Signature: pub struct PhextParseError;

What it does: A data shape named PhextParseError. The scanner did not read its fields.

(Where these words came from: signature.)


function — check_for_cowbell

Found in src/phext.rs at line 412.

Signature: pub fn check_for_cowbell(input: &str) -> bool {

What it does: Function check_for_cowbell takes input: &str and gives back bool.

(Where these words came from: signature.)


function — get_subspace_coordinates

Found in src/phext.rs at line 441.

Signature: pub fn get_subspace_coordinates(subspace: &[u8], target: Coordinate) -> (usize, usize, Coordinate) {

What it does: ---------------------------------------------------------------------------------------------------------- @fn get_subspace_coordinates finds the start and end offsets for the given coordinate Returns (start, end, best): - when the document reaches target, start..end is that scroll's text (empty if it has none) and best is target; - otherwise start == end is where the scroll would go: just before the break that steps past target, or the end of the document. best is the coordinate in effect there, so writing breaks from best up to target and then the text places it correctly. The walker only moves on a dimension break, so it is compared with target only at the start and after each break, and the scan stops as soon as it steps past target. Earlier versions returned start = 0 for a missing coordinate that falls between two scrolls, so fetch, replace, and remove acted on the scroll before it, and they missed a scroll reached only by breaks at the very end of the document. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — remove

Found in src/phext.rs at line 495.

Signature: pub fn remove(input: &str, location: Coordinate) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — create_summary

Found in src/phext.rs at line 501.

Signature: pub fn create_summary(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — navmap

Found in src/phext.rs at line 520.

Signature: pub fn navmap(urlbase: &str, input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — textmap

Found in src/phext.rs at line 538.

Signature: pub fn textmap(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — checksum

Found in src/phext.rs at line 553.

Signature: pub fn checksum(input: &str) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn checksum Provides a 128-bit content checksum using the fastest algorithm Rust provides: xxh3 ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — manifest

Found in src/phext.rs at line 560.

Signature: pub fn manifest(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — soundex_v1

Found in src/phext.rs at line 600.

Signature: pub fn soundex_v1(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — index

Found in src/phext.rs at line 638.

Signature: pub fn index(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — offset

Found in src/phext.rs at line 648.

Signature: pub fn offset(input: &str, coord: Coordinate) -> usize {

What it does: ---------------------------------------------------------------------------------------------------------- The offset of the scroll at coord, or of the last scroll before it. 0 when no scroll comes at or before coord (earlier versions panicked there).

(Where these words came from: doc comment.)


function — replace

Found in src/phext.rs at line 663.

Signature: pub fn replace(input: &str, location: Coordinate, scroll: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — range_replace

Found in src/phext.rs at line 725.

Signature: pub fn range_replace(input: &str, location: Range, scroll: &str) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- errata: libphext-py opted for ranges that operate on a stack of positioned scrolls this method applies the range edit to subspace directly...we probably need both

(Where these words came from: doc comment.)


function — insert

Found in src/phext.rs at line 750.

Signature: pub fn insert(input: String, location: Coordinate, scroll: &str) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn insert inserts the content specified in scroll at the coordinate within phext specified by location ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — next_scroll

Found in src/phext.rs at line 813.

Signature: pub fn next_scroll(input: &str, start: Coordinate) -> (PositionedScroll, Coordinate, String) {

What it does: ---------------------------------------------------------------------------------------------------------- @fn next_scroll retrieves the next scroll from the given string, assuming an arbitrary starting point ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — phokenize

Found in src/phext.rs at line 899.

Signature: pub fn phokenize(input: &str) -> Vec<PositionedScroll> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn phokenize Transforms a packed phext buffer into a phext token (phoken) stream One pass over the bytes. Each step matches a call to next_scroll: skip leading breaks, take a run of text, then consume the break that ends it. Earlier versions called next_scroll in a loop, which copied the rest of the document for every scroll and made this quadratic in the document size. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — explode

Found in src/phext.rs at line 942.

Signature: pub fn explode(input: &str) -> HashMap<Coordinate, String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn explode Explodes an input phext into a hierarchical hashap, suitable for fast access and updates ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


struct — ScrollSpan

Found in src/phext.rs at line 966.

Signature: pub struct ScrollSpan {

What it does: ---------------------------------------------------------------------------------------------------------- @struct ScrollSpan The borrowed form of a PositionedScroll: a scroll's coordinate plus the byte range of its text within the input document. Slicing the input with range yields exactly the scroll's text — building the index allocates no String per scroll. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — spans

Found in src/phext.rs at line 1012.

Signature: pub fn spans(input: &str) -> Vec<ScrollSpan> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn spans Builds a borrowed span index over input: one ScrollSpan per scroll, in document order, giving each scroll's coordinate and the byte range of its text in input. The walk is the phokenize walk — the same dimension breaks and the same coordinate arithmetic — except that it records byte ranges instead of allocating a String for every scroll. For every returned span, &input[span.range] is exactly the scroll explode returns at span.coord, and span.range.start is the offset offset reports for that coordinate. Empty-scroll contract: a scroll exists iff it holds at least one byte — the definition explode encodes — so spans reports only non-empty scrolls. Delimiter runs that encode empty scrolls (leading breaks, runs between distant scrolls, trailing breaks) produce no span; an empty document, or a document of only delimiters, produces no spans. phokenize remains the tokenizer of record for empty slots: it additionally reports a final empty positioned scroll in those trailing cases, where spans reports none. Chain bytes (0x02 / 0x03) are not dimension breaks, so — exactly as in phokenize and explode — they are scroll content here. This index covers a single phext (one universe); chain structure is the parse_chains layer above it. Motivating consumer: holo-phext, whose src/index.rs carries a 323-line re-implementation of this walk, plus a duplicated private dimension-break predicate in its core, because libphext exported only owned-String tokenization (phokenize/explode) and a single-scroll offset. Downstream stores should index with spans instead of re-walking the format. # Example `` use libphext::phext::{spans, to_coordinate}; let input = "alpha\u{17}beta"; let index = spans(input); assert_eq!(index.len(), 2); assert_eq!(index[0].coord, to_coordinate("1.1.1/1.1.1/1.1.1")); assert_eq!(&input[index[0].range.clone()], "alpha"); assert_eq!(&input[index[1].range.clone()], "beta"); `` ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


struct — TocChild

Found in src/phext.rs at line 1055.

Signature: pub struct TocChild {

What it does: ---------------------------------------------------------------------------------------------------------- @struct TocChild One entry in a toc_children listing: a value taken by the next dimension below a coordinate prefix, together with the number of scrolls and the total scroll bytes in that child's subtree. Structure only — no scroll text is copied or returned. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


struct — TocSummary

Found in src/phext.rs at line 1068.

Signature: pub struct TocSummary {

What it does: ---------------------------------------------------------------------------------------------------------- @struct TocSummary The aggregate shape of a coordinate prefix's subtree: how many scrolls it holds and how many bytes of scroll text they carry in total. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


struct — TocScroll

Found in src/phext.rs at line 1081.

Signature: pub struct TocScroll {

What it does: ---------------------------------------------------------------------------------------------------------- @struct TocScroll One entry in a toc_scrolls listing: a scroll's full coordinate and the byte length of its text. The planet list for progressive clients — coordinates and sizes, never bodies. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — toc_children

Found in src/phext.rs at line 1131.

Signature: pub fn toc_children(input: &str, prefix: &[usize]) -> Vec<TocChild> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn toc_children The progressive table of contents: given a coordinate prefix — the leading prefix.len() address components, 0 to 8 of them — returns one TocChild per distinct value the next dimension takes under that prefix, sorted ascending, each with the scroll count and total scroll bytes of its subtree. A client walking a phext from the root calls toc_children(input, &[]) for the libraries present, then toc_children(input, &[2]) for the shelves of library 2, and so on — downloading structure one level at a time instead of the whole document. Built on the spans index in a single pass; scroll bodies are never copied. A prefix of 9 or more components has no next dimension and yields an empty listing, as does a prefix no scroll matches. The children partition their parent: for any prefix shorter than 9 components, the scrolls of toc_children(input, prefix) sum to toc_summary(input, prefix).scrolls, and the bytes sum likewise. # Example `` use libphext::phext::toc_children; let input = "alpha\u{17}beta\u{18}gamma"; let root = toc_children(input, &[]); assert_eq!(root.len(), 1); assert_eq!(root[0].value, 1); assert_eq!(root[0].scrolls, 3); `` ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — toc_summary

Found in src/phext.rs at line 1154.

Signature: pub fn toc_summary(input: &str, prefix: &[usize]) -> TocSummary {

What it does: ---------------------------------------------------------------------------------------------------------- @fn toc_summary The size of a subtree: the number of scrolls under prefix (0 to 9 leading address components) and their total byte length. toc_summary(input, &[]) summarizes the whole document; a full 9-component prefix summarizes a single scroll — 1 scroll if it is populated, 0 if it is not. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — toc_scrolls

Found in src/phext.rs at line 1176.

Signature: pub fn toc_scrolls(input: &str, prefix: &[usize]) -> Vec<TocScroll> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn toc_scrolls Every scroll under prefix (0 to 9 leading address components), in document order, as a TocScroll: full coordinate plus byte length, no bodies. This is the planet list a progressive client renders at the bottom of a zoom — it asks for the scrolls of one star system, not of the whole phext. A full 9-component prefix yields the single scroll at that coordinate, if populated. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — toc_scrolls_by_suffix

Found in src/phext.rs at line 1199.

Signature: pub fn toc_scrolls_by_suffix(input: &str, suffix: &[usize]) -> Vec<TocScroll> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn toc_scrolls_by_suffix Every scroll whose coordinate ENDS with suffix — the trailing 1 to 9 address components — in document order, as TocScroll entries (coordinate + bytes, no bodies). The relationship primitive: scrolls that share a chapter.section.scroll suffix are related wherever their library-through-book parents live, and this is the query that finds them. A 9-component suffix is a full coordinate and yields at most one scroll; an empty suffix yields every scroll, as toc_scrolls(input, &[]) does. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — implode

Found in src/phext.rs at line 1217.

Signature: pub fn implode(map: HashMap::<Coordinate, String>) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn implode Serializes a hierarchical hash of scrolls into a monolithic phext document. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — merge

Found in src/phext.rs at line 1232.

Signature: pub fn merge(left: &str, right: &str) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn merge combines left and right into a new phext document, with content merged on a per-scroll basis ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — fetch

Found in src/phext.rs at line 1276.

Signature: pub fn fetch(input: &str, target: Coordinate) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn fetch retrieves the scroll located at the given coordinates. @param phext the raw phext buffer to search @param coord coordinate to select the scroll from ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — expand

Found in src/phext.rs at line 1301.

Signature: pub fn expand(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — contract

Found in src/phext.rs at line 1334.

Signature: pub fn contract(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — subtract

Found in src/phext.rs at line 1408.

Signature: pub fn subtract(left: &str, right: &str) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn subtract Subtracts the scrolls from left where there is also content at those coordinates in right Note: This makes it easy to generate a mask for a given phext archive. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — is_phext_break

Found in src/phext.rs at line 1438.

Signature: pub fn is_phext_break(byte: u8) -> bool {

What it does: ---------------------------------------------------------------------------------------------------------- @fn is_phext_break returns true if byte corresponds to one of our phext delimiters (line breaks included) ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — normalize

Found in src/phext.rs at line 1452.

Signature: pub fn normalize(input: &str) -> String {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


struct — Chain

Found in src/phext.rs at line 1473.

Signature: pub struct Chain {

What it does: ---------------------------------------------------------------------------------------------------------- @struct Chain A chain: an ordered series of complete phexts within one stream, joined by CHAIN_BREAK (0x02) and optionally terminated by CHAIN_CLOSE (0x03). The chain layer is a stream-level layer, one rung above the library break: the nine dimension breaks structure a single phext, while the two chain bytes structure a stream of phexts. Each member is a whole phext, worked with the ordinary phext functions in this module; read in succession, a chain's members are editions in sequence — the chain is how a phext stream encodes time. closed records how the chain ended: true when a CHAIN_CLOSE terminated it, false when the stream simply ran out (EOF). A chain that ends at EOF is unclosed — possibly truncated — and is never silently promoted to closed. A stream with no chain bytes at all is a single unclosed chain holding one member phext: every pre-0.6 phext reads this way. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — Chain::new

Found in src/phext.rs at line 1478.

Signature: pub fn new() -> Chain {

What it does: Function Chain::new takes no inputs beyond the value it is called on, and gives back Chain.

(Where these words came from: signature.)


function — serialize

Found in src/phext.rs at line 1488.

Signature: pub fn serialize(&self) -> String {

What it does: ------------------------------------------------------------------------------------------------------ @fn serialize serializes this chain alone: its members joined by CHAIN_BREAK, with a trailing CHAIN_CLOSE when the chain is closed. See serialize_chains for whole streams. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — parse_chains

Found in src/phext.rs at line 1511.

Signature: pub fn parse_chains(input: &str) -> Vec<Chain> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn parse_chains splits a stream into its chains. CHAIN_BREAK separates the member phexts of a chain; CHAIN_CLOSE terminates a chain, and whatever follows it opens the next one — so one stream may hold many chains. The stream's final chain is closed only when the stream ends with CHAIN_CLOSE. Splitting follows split_on semantics, so empty members and empty chains are preserved exactly: parse and serialize are byte-exact inverses for every stream. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — serialize_chains

Found in src/phext.rs at line 1535.

Signature: pub fn serialize_chains(chains: &[Chain]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn serialize_chains serializes a stream of chains back into stream bytes: the inverse of parse_chains. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — default_coordinate

Found in src/phext.rs at line 1544.

Signature: pub fn default_coordinate() -> Coordinate {

What it does: ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — to_coordinate

Found in src/phext.rs at line 1572.

Signature: pub fn to_coordinate(address: &str) -> Coordinate {

What it does: ---------------------------------------------------------------------------------------------------------- @fn to_coordinate translates a phext string to a strongly-typed address @param address text to parse ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — Coordinate::validate_coordinate

Found in src/phext.rs at line 1623.

Signature: pub fn validate_coordinate(&self) -> bool {

What it does: ---------------------------------------------------------------------------------------------------------- @fn validate_coordinate determines if coord points to a valid phext address @param coord: the coordinate to reset ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — to_string

Found in src/phext.rs at line 1643.

Signature: pub fn to_string(&self) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn to_string produces a quoted string for the given phext address in canonical format (z3.z2.z1/y3.y2.y1/x3.x2.x1) @param coord the coordinate to translate ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — to_urlencoded

Found in src/phext.rs at line 1653.

Signature: pub fn to_urlencoded(&self) -> String {

What it does: Function to_urlencoded takes no inputs beyond the value it is called on, and gives back String.

(Where these words came from: signature.)


function — scroll_break

Found in src/phext.rs at line 1674.

Signature: pub fn scroll_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn scroll_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — section_break

Found in src/phext.rs at line 1681.

Signature: pub fn section_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn section_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — chapter_break

Found in src/phext.rs at line 1689.

Signature: pub fn chapter_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn chapter_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — book_break

Found in src/phext.rs at line 1698.

Signature: pub fn book_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn book_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — volume_break

Found in src/phext.rs at line 1708.

Signature: pub fn volume_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn volume_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — collection_break

Found in src/phext.rs at line 1719.

Signature: pub fn collection_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn collection_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — series_break

Found in src/phext.rs at line 1731.

Signature: pub fn series_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn series_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — shelf_break

Found in src/phext.rs at line 1744.

Signature: pub fn shelf_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn shelf_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — library_break

Found in src/phext.rs at line 1758.

Signature: pub fn library_break(&mut self) {

What it does: ------------------------------------------------------------------------------------------------------ @fn library_break ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — parse_universe_address

Found in src/phext.rs at line 1775.

Signature: pub fn parse_universe_address(address: &str) -> Option<(usize, Coordinate)> {

What it does: Function parse_universe_address takes address: &str and gives back Option<(usize, Coordinate)>.

(Where these words came from: signature.)


function — Chain::fetch

Found in src/phext.rs at line 1791.

Signature: pub fn fetch(&self, address: &str) -> String {

What it does: Fetch a scroll by multiverse address: "$N:coord", or a bare coordinate (universe 1). Out-of-range universes and missing scrolls yield an empty string, as fetch does.

(Where these words came from: doc comment.)


struct — ScrollPosition

Found in src/phext.rs at line 1825.

Signature: pub struct ScrollPosition {

What it does: @struct ScrollPosition A caret boundary inside one scroll: 1-based line and column (see the section note above).

(Where these words came from: doc comment.)


struct — PointAddress

Found in src/phext.rs at line 1835.

Signature: pub struct PointAddress {

What it does: @struct PointAddress One parsed point address: universe (1-based; 1 when the "$N:" prefix is absent), the 9D coordinate, an optional caret position, and an optional forward offset in characters.

(Where these words came from: doc comment.)


struct — RangeAddress

Found in src/phext.rs at line 1859.

Signature: pub struct RangeAddress {

What it does: @struct RangeAddress A parsed range: two point endpoints, normalized to ascending order at parse time.

(Where these words came from: doc comment.)


function — parse_point_address

Found in src/phext.rs at line 1900.

Signature: pub fn parse_point_address(address: &str) -> Option<PointAddress> {

What it does: ------------------------------------------------------------------------------------------------------ @fn parse_point_address parses a v0.6.1 point address: "[$N:]<coordinate>[@<line>,<column>[+<offsetChars>]]". Returns None on any malformed input: universe 0, a coordinate component below 1, a line or column below 1, a sign anywhere, or trailing structure. "$1:" is accepted on input; the canonical Display form never emits it. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — parse_range_address

Found in src/phext.rs at line 1958.

Signature: pub fn parse_range_address(address: &str) -> Option<RangeAddress> {

What it does: ------------------------------------------------------------------------------------------------------ @fn parse_range_address parses a v0.6.1 range address: exactly two point addresses joined by one hyphen. The endpoints are normalized to ascending order (direction is discarded, per the ratified spec). Range endpoints may not carry a "+offset" — the offset form never takes a second endpoint. Returns None on malformed input. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — Chain::resolve_point

Found in src/phext.rs at line 2000.

Signature: pub fn resolve_point(&self, point: &PointAddress) -> Option<(usize, Coordinate, usize)> {

What it does: ------------------------------------------------------------------------------------------------------ @fn resolve_point resolves a point address against this chain: (universe, coordinate, character offset within the scroll). A point without "@" resolves to offset 0 of its scroll. None when the universe or scroll is absent or the position is out of range — never clamps. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — fetch_point

Found in src/phext.rs at line 2018.

Signature: pub fn fetch_point(&self, address: &str) -> String {

What it does: ------------------------------------------------------------------------------------------------------ @fn fetch_point fetches a point address string. A bare point is a caret: it fetches the empty string. The offset form fetches the selected characters: from the point, forward offset characters (scalars) within the scroll, terminating at the scroll boundary. Any parse or resolution failure fetches the empty string, as Chain::fetch does. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — resolve_range

Found in src/phext.rs at line 2035.

Signature: pub fn resolve_range(&self, range: &RangeAddress) -> Option<Vec<(usize, Coordinate, String)>> {

What it does: ------------------------------------------------------------------------------------------------------ @fn resolve_range resolves a range against this chain into per-scroll segments: (universe, coordinate, segment text) in ascending order. Middle scrolls contribute their whole text; the endpoint scrolls contribute from/to their endpoint boundaries (an endpoint without "@" contributes its whole scroll). None when either endpoint fails to resolve — an out-of-range endpoint is an error, never a clamp. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — fetch_range

Found in src/phext.rs at line 2077.

Signature: pub fn fetch_range(&self, address: &str) -> String {

What it does: ------------------------------------------------------------------------------------------------------ @fn fetch_range fetches a range address string: the spanned text with phext structure bytes preserved — the covered segments re-assembled at their coordinates into a phext (chain) fragment (scroll breaks between covered scrolls inside a universe, CHAIN_BREAK between universes, never a trailing CHAIN_CLOSE: a fragment is an excerpt, not a terminated chain), so the result round-trips as a phext fragment. Empty segments contribute nothing. Any parse or resolution failure fetches the empty string, as Chain::fetch does. ------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — checked_scroll

Found in src/phext.rs at line 2123.

Signature: pub fn checked_scroll(scroll: &str) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn checked_scroll Returns scroll with an integrity trailer appended: one final line phext-check:xxh3-128:<checksum of the payload>. In a checked scroll the final line is reserved — verification always reads the LAST marker line, and the checksum binds the entire payload before it, so a marker line inside the payload cannot forge a trailer. The checksum detects accidental corruption and torn writes. xxh3 is not a cryptographic hash: this is integrity, not authentication. An empty scroll stays empty (a scroll with no bytes does not exist, so there is nothing to check). ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — verify_checked_scroll

Found in src/phext.rs at line 2136.

Signature: pub fn verify_checked_scroll(scroll: &str) -> bool {

What it does: ---------------------------------------------------------------------------------------------------------- @fn verify_checked_scroll true when scroll ends with a well-formed integrity trailer whose checksum matches the payload before it. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — uncheck_scroll

Found in src/phext.rs at line 2153.

Signature: pub fn uncheck_scroll(scroll: &str) -> Option<String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn uncheck_scroll Returns the payload of a checked scroll when its trailer verifies; None for unchecked, malformed, or corrupted scrolls. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — fetch_checked

Found in src/phext.rs at line 2174.

Signature: pub fn fetch_checked(input: &str, target: Coordinate) -> Option<String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn fetch_checked Fetches the scroll at target and returns its payload, but only when the scroll is checked and verifies. A missing, unchecked, or torn scroll yields None — recovery code can treat None as "not committed". This is a single-scroll lookup: one early-exit scan, linear in the document, with no per-entry repetition inside the call. Callers that verify a whole batch should use verify_commit, which indexes the document once for the marker and every entry. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — append

Found in src/phext.rs at line 2317.

Signature: pub fn append(input: String, location: Coordinate, scroll: &str) -> Option<String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn append Appends scroll at location, which must sort strictly after the document's last non-empty scroll. The result is the input with only a delimiter run and the new content added at its end — a host can write just that suffix to a file opened in append mode and sync once. Returns None when the scroll is empty (empty scrolls do not exist) or location does not sort after the document's end. Trailing delimiter bytes in the input encode only empty scrolls, so they are dropped first and never shift the appended scroll's address. On None the append was rejected; the input String was consumed, so pass a clone if the caller needs it after a rejected append. The document's end is located with last_scroll_coordinate, a backward delimiter scan over the bytes — existing text is never re-tokenized, so a call's cost tracks the delimiter run at the end of the document, not the size of the document. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — append_checked

Found in src/phext.rs at line 2351.

Signature: pub fn append_checked(input: String, location: Coordinate, scroll: &str) -> Option<String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn append_checked append with an integrity trailer: the stored scroll is checked_scroll(scroll), verifiable later with fetch_checked. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — append_batch

Found in src/phext.rs at line 2369.

Signature: pub fn append_batch(input: String, entries: &[(Coordinate, &str)]) -> Option<String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn append_batch Appends several scrolls in one call. Entries must be non-empty and in strictly ascending coordinate order, the first sorting after the document's end. The whole batch is a single suffix of the result, so a host persists it with one write and one sync. This is construction atomicity, not storage atomicity: whether the suffix lands completely is the host filesystem's business (see the durability profile in the crate docs). Pair the batch with a commit_scroll as its final entry to make a torn batch detectable at recovery — that is the part a format library can own. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — commit_scroll

Found in src/phext.rs at line 2400.

Signature: pub fn commit_scroll(entries: &[(Coordinate, &str)]) -> String {

What it does: ---------------------------------------------------------------------------------------------------------- @fn commit_scroll Builds the commit marker for a batch: a small scroll binding the batch's entry count and a checksum over each entry's coordinate and content, in order. Append it (via append_batch) as the batch's final scroll, at a coordinate after every entry. entries here are the (coordinate, content) pairs exactly as appended — checked contents included, when the batch uses checked scrolls. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — verify_commit

Found in src/phext.rs at line 2425.

Signature: pub fn verify_commit(input: &str, entries: &[Coordinate], commit: Coordinate) -> bool {

What it does: ---------------------------------------------------------------------------------------------------------- @fn verify_commit true when the scroll at commit is a commit marker whose count matches entries and whose checksum matches the entries' current contents, in order. Any missing, altered, or torn entry — or a missing marker — yields false: the batch did not commit. The document is indexed with a single explode pass and the marker and every entry are read from that map. The previous implementation ran the scanning fetch once for the marker and once per entry, so verification cost grew quadratically in document length — the cost a WAL recovery pass pays over the whole log, per transaction. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


const — SEAL_PRESET

Found in src/seal.rs at line 22.

Signature: pub const SEAL_PRESET: u32 = 6;

What it does: The xz preset this implementation seals with.

(Where these words came from: doc comment.)


function — seal

Found in src/seal.rs at line 29.

Signature: pub fn seal(input: &str) -> io::Result<Vec<u8>> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn seal seals a phext: xz-compresses its full UTF-8 bytes. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — seal_bytes

Found in src/seal.rs at line 38.

Signature: pub fn seal_bytes(input: &[u8]) -> io::Result<Vec<u8>> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn seal_bytes seals raw phext bytes (see seal). ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — unseal

Found in src/seal.rs at line 50.

Signature: pub fn unseal(data: &[u8]) -> io::Result<Vec<u8>> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn unseal unseals a sealed phext back to its exact original bytes. Returns the io error when the data is not a valid xz stream. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


function — unseal_string

Found in src/seal.rs at line 65.

Signature: pub fn unseal_string(data: &[u8]) -> io::Result<String> {

What it does: ---------------------------------------------------------------------------------------------------------- @fn unseal_string unseals directly to text. Fails with InvalidData when the unsealed bytes are not valid UTF-8; to unseal foreign content that may carry non-UTF-8 scrolls, unseal to bytes and pass them through binary::ingest, which applies the base64-verbatim ingestion rule instead of failing. ----------------------------------------------------------------------------------------------------------

(Where these words came from: doc comment.)


Provenance

This documentation is produced for the export repo wbic16/phdoc (its chain of record lives at docs/libphext-rs/chain.phext) and for the doc site https://docs.phext.io. Both targets are the project's own configuration, held in its .phdoc.json as "export-repo" and "doc-site"; when a project does not name them, the defaults are wbic16/phdoc and https://docs.phext.io.

Historical reference · chain.phext · latest.md