Skip to main content

BYTES

Constant BYTES 

Source
pub const BYTES: &str = "//! `Bytes`, an immutable buffer of bytes, and the functions that make one.\n//!\n//! The bytes of a `Bytes` value carry no encoding, where a `String`\'s are\n//! always UTF-8, and nothing converts between the two implicitly.\n//! `bytes_from_string` and `bytes_from_ints` make a `Bytes`, and its methods\n//! measure, index, slice, join and search it, all counting in bytes; none\n//! changes it. `to_string` turns bytes that are valid UTF-8 back into a\n//! `String`. `Bytes` implements `Eq`: `a.eq(b)` compares two buffers byte for\n//! byte.\n//!\n//! Making `Bytes` from a string and from integers, measuring, slicing,\n//! joining and searching them, and turning them back into a `String`:\n//!\n//! ```\n//! let greeting = bytes_from_string(\"hi!\")\n//! assert_eq(greeting.len(), 3)\n//! assert_eq(greeting.byte_at(0).unwrap(), 104) // \'h\'\n//! assert_eq(greeting.slice(1, 99).to_string().unwrap(), \"i!\") // bounds are clamped\n//!\n//! let line = greeting.concat(bytes_from_ints([10])) // a line feed\n//! assert(line.eq(bytes_from_string(\"hi!\\n\")), \"equal byte for byte\")\n//! assert_eq(line.index_of(bytes_from_string(\"!\")).unwrap(), 2)\n//!\n//! // Bytes carry no encoding: these two are not valid UTF-8.\n//! let raw = bytes_from_ints([0xff, 0xfe])\n//! assert(raw.to_string().is_none(), \"not UTF-8, so no String\")\n//! ```\n\n// Nova standard library \u{2014} byte buffers.\n//\n// Compiled as an implicit module and glob-imported into every user module, so\n// these names need no `import` (see docs/adr/0004-stdlib-compile-model.md).\n//\n// `Bytes` is an immutable byte buffer. It shares `String`\'s representation --\n// a `{len, ptr}` leaf header, and every `Bytes` value is one object with its\n// bytes inline after it -- and differs in carrying no encoding guarantee.\n// Nothing converts between them implicitly.\n//\n// This module follows `std/strings`\' structure: a small intrinsic core with the\n// searching and bounds checking done here in Nova, rather than one intrinsic per\n// method.\n\nimpl Bytes {\n    // The number of bytes. Not a character count: `Bytes` has no encoding.\n    /// Returns the number of bytes.\n    pub fn len(self) -> Int { bytes_len(self) }\n\n    // These bytes as a `String`, or `None` if they are not valid UTF-8.\n    //\n    // `Option` rather than `Result<String, IoError>`: there is exactly one way\n    // this fails, so an error kind would carry no information, and a byte type\n    // should not depend on an I/O error type.\n    /// Returns the bytes as a `String`, or `None` if they are not valid UTF-8.\n    pub fn to_string(self) -> Option<String> {\n        if bytes_is_utf8(self) { Some(bytes_to_string_unchecked(self)) } else { None }\n    }\n\n    // The byte at `i`, or `None` if `i` is out of range.\n    //\n    // `Option` rather than an abort, matching `String::char_at`; a negative\n    // index is `None` for the same reason.\n    /// Returns the byte at index `i`, as an `Int` from 0 to 255, or `None` if\n    /// `i` is negative or not less than `len()`.\n    pub fn byte_at(self, i: Int) -> Option<Int> {\n        if i < 0 { return None }\n        if i >= self.len() { return None }\n        Some(bytes_at(self, i))\n    }\n\n    // The bytes in `start..end`, clamped to this buffer. Deliberately NOT\n    // what `String::slice` does -- that one panics on an out-of-range bound.\n    // A `Bytes` length often comes from disk rather than from a caller who\n    // already knows it, so clamping (rather than aborting the process) is\n    // the better failure mode here. Recorded, accepted divergence -- see the\n    // design spec\'s dated note -- not a claim that `String::slice` agrees.\n    /// Returns the bytes from index `start` up to, but not including, `end`.\n    ///\n    /// Unlike `String::slice`, it never panics: each bound is clamped to\n    /// `0..=len()`, and a `start` at or after `end` gives empty bytes.\n    pub fn slice(self, start: Int, end: Int) -> Bytes { bytes_slice(self, start, end) }\n\n    // These bytes followed by `other`\'s.\n    /// Returns these bytes followed by `other`\'s.\n    pub fn concat(self, other: Bytes) -> Bytes { bytes_concat(self, other) }\n\n    // Each byte as an `Int` in `0..=255`.\n    /// Returns each byte as an `Int` from 0 to 255, in order.\n    pub fn to_ints(self) -> [Int] { bytes_to_ints(self) }\n\n    // The index of `needle`\'s first occurrence, or `None`.\n    //\n    // Searched here in Nova over an `[Int]` rather than by an intrinsic -- one\n    // runtime call per operand instead of one per byte compared. That is the\n    // shape `String::index_of` used over `str_chars` until 2026-10-02, when it\n    // moved to a runtime byte search.\n    /// Returns the index at which `needle` first occurs, or `None` if it does\n    /// not occur.\n    ///\n    /// An empty `needle` occurs at index 0.\n    pub fn index_of(self, needle: Bytes) -> Option<Int> {\n        let h = self.to_ints()\n        let n = needle.to_ints()\n        if n.len() == 0 { return Some(0) }\n        if n.len() > h.len() { return None }\n        let last = h.len() - n.len()\n        let mut at = 0\n        while at <= last {\n            let mut k = 0\n            let mut same = true\n            while k < n.len() {\n                if h[at + k] != n[k] { same = false }\n                k = k + 1\n            }\n            if same { return Some(at) }\n            at = at + 1\n        }\n        None\n    }\n\n    // Whether `needle` occurs in these bytes.\n    /// Returns `true` if `needle` occurs in these bytes. An empty `needle`\n    /// always does.\n    pub fn contains(self, needle: Bytes) -> Bool { self.index_of(needle).is_some() }\n}\n\n// A `Bytes` holding `s`\'s UTF-8 bytes.\n//\n// A free function rather than a method on `String`, so `std/strings` needs no\n// knowledge of `Bytes`.\n//\n// Calls `bytes_from_string_intrinsic`, not a builtin of this same name: this\n// module is itself a `STD_MODULES` entry, so `Builtin::STD_ONLY` -- including\n// the builtin backing this very function -- is seeded into this module\'s own\n// scope before this function is collected (`nova_resolver::resolve_program`\'s\n// pass order). A builtin named `bytes_from_string` here would make this\n// definition collide with itself: `insert_value` reports `E0002 duplicate\n// definition` (\"is a compiler builtin\") rather than silently compiling the\n// call below into a recursive call, and rather than silently letting this\n// definition shadow the builtin -- there is no such shadowing path for a\n// module\'s own item colliding with something already in its own scope. See\n// `Builtin::BytesFromString`\'s doc comment (`nova-resolver`) and the Task 2\n// report for the verification.\n/// Returns the UTF-8 bytes of `s`.\npub fn bytes_from_string(s: String) -> Bytes { bytes_from_string_intrinsic(s) }\n\n// A `Bytes` holding each `Int` in `ints` as one byte.\n//\n// Aborts if any element is outside `0..=255`: that is a caller error, and a\n// `Result` here would infect every construction path.\n//\n// Calls `bytes_from_ints_intrinsic`, not a builtin of this same name, for the\n// same reason `bytes_from_string` above calls `bytes_from_string_intrinsic`:\n// this module is a `STD_MODULES` entry, so a builtin named `bytes_from_ints`\n// would collide with this very definition (`E0002`) rather than being called\n// by it. See `Builtin::BytesFromInts`\'s doc comment (`nova-resolver`).\n/// Returns a `Bytes` holding each `Int` of `ints` as one byte, in order.\n///\n/// Panics if any element is outside `0..=255`.\npub fn bytes_from_ints(ints: [Int]) -> Bytes { bytes_from_ints_intrinsic(ints) }\n\nimpl Eq for Bytes {\n    fn eq(self, other: Bytes) -> Bool { bytes_eq(self, other) }\n}\n";
Expand description

std/bytes/lib.nova.