Module std::bytes

Byte strings: searching, splitting, trimming and bounds-checked ranges over &[u8], the ASCII classes and case mappings of a byte and of &[u8], and decimal integers parsed from bytes and formatted into them. Reach for it on paths, protocol fields and a String's bytes (as_bytes) before or without UTF-8 validation. Nothing here panics: a bad range is None; only the copying case mappings allocate.

Source: std/bytes.weir; committed interface: std/bytes.iface. Index

enum ParseIntError

pub enum ParseIntError: copy {
    Empty,
    InvalidDigit(usize),
    Overflow,
}

Why parse_int refused its bytes.

Variants:

fn find_byte

pub fn find_byte(b: &[u8], x: u8) -> Option<usize>

The first index holding x, or None when b has no such byte. O(n).

Committed interface (std/bytes.iface): the signature alone.

fn find

pub fn find(b: &[u8], needle: &[u8]) -> Option<usize>

The first index where needle starts in b, or None; an empty needle is found at 0. Naive search, O(n·m).

Committed interface (std/bytes.iface): the signature alone.

fn starts_with

pub fn starts_with(b: &[u8], p: &[u8]) -> Bool

Whether b begins with p.

Committed interface (std/bytes.iface): the signature alone.

fn ends_with

pub fn ends_with(b: &[u8], p: &[u8]) -> Bool

Whether b ends with p.

Committed interface (std/bytes.iface): the signature alone.

fn is_ascii_whitespace

pub fn is_ascii_whitespace(c: u8) -> Bool

Whether c is ASCII whitespace: space, tab, line feed, form feed or carriage return, as Rust's u8::is_ascii_whitespace (no vertical tab).

Committed interface (std/bytes.iface): the signature alone.

fn is_ascii_digit

pub fn is_ascii_digit(c: u8) -> Bool

Whether c is 0 through 9.

Committed interface (std/bytes.iface): the signature alone.

fn is_ascii_uppercase

pub fn is_ascii_uppercase(c: u8) -> Bool

Whether c is A through Z.

Committed interface (std/bytes.iface): the signature alone.

fn is_ascii_lowercase

pub fn is_ascii_lowercase(c: u8) -> Bool

Whether c is a through z.

Committed interface (std/bytes.iface): the signature alone.

fn is_ascii_alphabetic

pub fn is_ascii_alphabetic(c: u8) -> Bool

Whether c is an ASCII letter of either case.

Committed interface (std/bytes.iface): the signature alone.

fn is_ascii_alphanumeric

pub fn is_ascii_alphanumeric(c: u8) -> Bool

Whether c is an ASCII letter or digit.

Committed interface (std/bytes.iface): the signature alone.

fn ascii_lower

pub fn ascii_lower(c: u8) -> u8

c with A–Z mapped to a–z; every other byte as it is.

Committed interface (std/bytes.iface): the signature alone.

fn ascii_upper

pub fn ascii_upper(c: u8) -> u8

c with a–z mapped to A–Z; every other byte as it is.

Committed interface (std/bytes.iface): the signature alone.

fn make_ascii_lowercase

pub fn make_ascii_lowercase(b: &mut [u8])

Lowercases the ASCII letters of b in place; every other byte, a UTF-8 sequence's among them, stays as it is, so UTF-8 text stays UTF-8. No allocation.

Committed interface (std/bytes.iface):

writes through b: everything

fn make_ascii_uppercase

pub fn make_ascii_uppercase(b: &mut [u8])

Uppercases the ASCII letters of b in place; every other byte stays as it is.

Committed interface (std/bytes.iface):

writes through b: everything

fn to_ascii_lowercase

pub fn to_ascii_lowercase(b: &[u8]) -> Buf<u8> with Alloc

A lowercased copy of b in a new buffer, hence Alloc; make_ascii_lowercase changes b in place instead.

Committed interface (std/bytes.iface):

bound Alloc: Alloc any
aborts: Alloc.alloc

fn to_ascii_uppercase

pub fn to_ascii_uppercase(b: &[u8]) -> Buf<u8> with Alloc

An uppercased copy of b in a new buffer, hence Alloc.

Committed interface (std/bytes.iface):

bound Alloc: Alloc any
aborts: Alloc.alloc

fn eq_ignore_ascii_case

pub fn eq_ignore_ascii_case(a: &[u8], b: &[u8]) -> Bool

Whether a and b are equal once their ASCII letters are lowercased; no allocation.

Committed interface (std/bytes.iface): the signature alone.

fn range

pub fn range(b: &[u8], lo: usize, hi: usize) -> Option<&[u8]>

Bytes lo..hi of b, or None unless lo <= hi <= b.len(); the non-panicking &b[lo..hi].

Committed interface (std/bytes.iface): the signature alone.

fn trim_start

pub fn trim_start(b: &[u8]) -> &[u8]

b without its leading ASCII whitespace (see is_ascii_whitespace); a view, no copy.

Committed interface (std/bytes.iface):

may diverge

fn trim_end

pub fn trim_end(b: &[u8]) -> &[u8]

b without its trailing ASCII whitespace; a view, no copy.

Committed interface (std/bytes.iface):

may diverge

fn trim

pub fn trim(b: &[u8]) -> &[u8]

b without its leading and trailing ASCII whitespace; a view, no copy.

Committed interface (std/bytes.iface):

may diverge

fn split_once

pub fn split_once(b: &[u8], sep: u8) -> Option<(&[u8], &[u8])>

The bytes before the first sep and those after it, or None when b holds no sep. Both are views of b alone, so one may be kept while the other is split again (Rust's split_once).

Committed interface (std/bytes.iface):

may diverge

struct Split

pub struct Split {
    /* private fields */
}

The fields of a byte string, from split: for f in split(b, sep) { … } visits each. A field is a view of the bytes split, good until the cursor's next pull; fields to hold side by side come from split_once.

impl Split

method next

pub fn next(&mut self) -> Option<&[u8]>

The next field, or None after the last.

Committed interface (std/bytes.iface):

may diverge
writes through self: {done, rest}

fn split

pub fn split(b: &[u8], sep: u8) -> Split

The fields of b between occurrences of sep, empty ones included: n separators give n + 1 fields, so an empty b has one empty field (Rust's split).

Committed interface (std/bytes.iface): the signature alone.

struct Lines

pub struct Lines {
    /* private fields */
}

The lines of a byte string, from lines: for l in lines(b) { … } visits each. A line is a view of the bytes split, good until the cursor's next pull.

impl Lines

method next

pub fn next(&mut self) -> Option<&[u8]>

The next line, or None after the last.

Committed interface (std/bytes.iface):

may diverge
writes through self: {rest}

fn lines

pub fn lines(b: &[u8]) -> Lines

The lines of b: each run of bytes up to a \n, without it and without a \r before it, then what follows the last \n unless that is empty. So an empty b has no line, a final \n adds none, and a last line ending in a bare \r keeps it (Rust's lines).

Committed interface (std/bytes.iface): the signature alone.

fn parse_int

pub fn parse_int(b: &[u8]) -> Result<Int, ParseIntError>

Parses a decimal Int: an optional - or +, then one or more ASCII digits, nothing else (no whitespace; trim first if needed). The Err says why: see ParseIntError.

Committed interface (std/bytes.iface):

may diverge

fn decimal_tail

pub fn decimal_tail(d: &mut [u8; 21], neg: Bool, u: u64) -> usize

Writes the decimal digits of u, after a - when neg, at the end of d and answers the index of the first byte written: the text is &d[k..], at most 21 bytes. What fmt_int, fmt_uint and String's integer Display share; reach for it to right-align a number.

Committed interface (std/bytes.iface):

may diverge
writes through d: everything

fn hex_tail

pub fn hex_tail(d: &mut [u8; 16], x: u64) -> usize

Writes the lowercase hexadecimal digits of x, with no 0x, at the end of d and answers the index of the first byte written: the text is &d[k..], at most 16 bytes. What fmt_hex and String::push_hex share.

Committed interface (std/bytes.iface):

may diverge
writes through d: everything

fn fmt_int

pub fn fmt_int(b: &mut [u8], x: Int) -> Option<usize>

Writes x in decimal at the start of b, a - first when it is negative, and answers the count of bytes written (20 at most), or None, b untouched, when b is shorter than the text. No allocation; parse_int reads it back.

Committed interface (std/bytes.iface):

may diverge
writes through b: everything

fn fmt_uint

pub fn fmt_uint(b: &mut [u8], x: u64) -> Option<usize>

Writes x in decimal at the start of b and answers the count of bytes written (20 at most), or None, b untouched, when b is shorter than the text. A usize goes in as n.wrap::<u64>().

Committed interface (std/bytes.iface):

may diverge
writes through b: everything

fn fmt_hex

pub fn fmt_hex(b: &mut [u8], x: u64) -> Option<usize>

Writes x in lowercase hexadecimal, with no 0x, at the start of b and answers the count of bytes written (16 at most), or None, b untouched, when b is shorter than the text.

Committed interface (std/bytes.iface):

may diverge
writes through b: everything