class Bytes

include Comparable[Bytes], Enumerable[Int]

An immutable sequence of bytes: binary data, which a String (always UTF-8) does not hold.

The elements are Ints from 0 to 255. Indices, sizes and the positions the searching methods take and return are byte offsets, never characters. A literal is written b"\x00\xff"; Bytes::Builder builds one piece by piece, and String#to_bytes and #decode convert between text and bytes.

data = b"h\xc3\xa9llo"
data.size                # => 6
data.decode.size         # => 5
data[1]                  # => 195
data.index(b"l")         # => 3

<prelude>:1294

Classes and modules

Class methods

def self.new -> Bytes

Empty bytes.

<prelude>:1300

def self.[](*bytes: Int) -> Bytes

The bytes given, in order.

Raises RangeError for a value outside 0..255.

Bytes[104, 105]          # => b"hi"
Bytes[256]               # raises RangeError

<prelude>:1309

def self.from(bytes: Array[Int]) -> Bytes

The elements of bytes, in order. Raises RangeError for a value outside 0..255.

<prelude>:1312

def self.from_hex(hex: String) -> Bytes

The bytes the hexadecimal digits of hex spell, two digits a byte, in either case: the inverse of #hex.

Whitespace is ignored, even between the two digits of a byte. An odd number of digits or any other character (a 0x prefix too) raises ArgumentError.

Bytes.from_hex("00ff 7F")   # => b"\x00\xff\x7f"
Bytes.from_hex("abc")       # raises ArgumentError

<prelude>:1324

def self.build(&: (Bytes::Builder) -> Void) -> Bytes

Calls the block with a new Bytes::Builder and returns what it holds afterwards.

Bytes.build { |b| b << 104 << "é" }   # => b"h\xc3\xa9"

<prelude>:1331

Methods

def each(&: (Int) -> Void) -> Void

Calls the block with each byte, first to last.

<prelude>:1334

def each_byte(&: (Int) -> Void) -> Void

Calls the block with each byte, first to last: the same as #each.

<prelude>:1336

def size -> Int

The number of bytes.

<prelude>:1338

def length -> Int

The number of bytes: the same as #size.

<prelude>:1340

def bytesize -> Int

The number of bytes: the same as #size.

<prelude>:1342

def empty? -> Bool

Whether there is no byte.

<prelude>:1344

def [](index: Int) -> Int

The byte at index, counted from the end when negative.

Raises IndexError when index is out of range; #[]? returns nil instead.

b"abc"[-1]               # => 99
b"abc"[3]                # raises IndexError

<prelude>:1354

def [](range: Range[Int]) -> Bytes

The bytes in range, whose ends count from the end when negative. The end is cut to the size; a start equal to the size gives empty bytes.

Raises

IndexError when the start is beyond the size or before the beginning.

b"abcd"[1..2]            # => b"bc"
b"abcd"[-2..]            # => b"cd"
b"abcd"[2..10]           # => b"cd"
b"abcd"[4..]             # => b""
b"abcd"[6..8]            # raises IndexError

<prelude>:1370

def []?(index: Int) -> Int?

The byte at index, counted from the end when negative, or nil when it is out of range.

<prelude>:1373

def slice(start: Int, length: Int) -> Bytes

The length bytes from start (counted from the end when negative), or fewer when the end comes first.

start may be the size, giving empty bytes; beyond it raises IndexError. A negative length gives empty bytes.

b"abcd".slice(1, 2)      # => b"bc"
b"abcd".slice(-1, 5)     # => b"d"
b"abcd".slice(5, 1)      # raises IndexError

<prelude>:1385

def +(other: Bytes) -> Bytes

The bytes of self followed by those of other.

<prelude>:1387

def ==(other: Object) -> Bool

Whether other is Bytes with the same bytes. A String is never equal to Bytes, whatever its bytes.

<prelude>:1390

def <=>(other: Bytes) -> Int

Compares byte by byte as unsigned values, a prefix first: -1, 0 or 1.

b"ab" <=> b"abc"         # => -1
b"\xff" > b"a"           # => true

<prelude>:1397

def hash -> Int

A hash code consistent with #==, so that Bytes can be a Hash key or a Set member.

<prelude>:1400

def reverse -> Bytes

The bytes in reverse order.

<prelude>:1402

def to_a -> Array[Int]

The bytes as an array of Ints.

<prelude>:1404

def decode -> String

The bytes read as UTF-8 text.

Raises ArgumentError, naming the byte offset of the first invalid sequence, when they are not valid UTF-8; #decode? returns nil instead.

b"h\xc3\xa9".decode      # => "hé"
b"\xff".decode           # raises ArgumentError

<prelude>:1415

def decode(encoding: String) -> String

The bytes read as text in encoding.

The encodings are "UTF-8" (or "UTF8"), "ASCII" (or "US-ASCII") and "ISO-8859-1" (or "LATIN1", "LATIN-1"), in either case. Raises ArgumentError for another name, or for a byte sequence invalid in the encoding (a byte above 0x7F in ASCII); every byte is valid in ISO-8859-1.

b"\xe9".decode("ISO-8859-1")   # => "é"
b"\xe9".decode("ASCII")        # raises ArgumentError

<prelude>:1427

def decode? -> String?

The bytes read as UTF-8 text, or nil when they are not valid UTF-8.

<prelude>:1429

def hex -> String

The bytes in lowercase hexadecimal, two digits a byte. Bytes.from_hex reads it back.

b"\x00\xff".hex          # => "00ff"

<prelude>:1436

def to_s -> String

The literal form, as #inspect: puts shows b"...". Use #decode for the text the bytes hold.

<prelude>:1439

def inspect -> String

The literal form, b"...": printable ASCII as is (with \" and \\), \n, \t and \r, and any other byte as \xNN in lowercase.

b"a\n\xff".inspect       # => "b\"a\\n\\xff\""

<prelude>:1446

def start_with?(prefix: Bytes) -> Bool

Whether the bytes start with prefix.

<prelude>:1452

def start_with?(pattern: Regexp) -> Bool

Whether pattern matches at the start of the bytes.

<prelude>:1454

def end_with?(suffix: Bytes) -> Bool

Whether the bytes end with suffix.

<prelude>:1456

def include?(other: Bytes) -> Bool

Whether other occurs in the bytes. With an Int, include? is Enumerable#include?: whether that byte occurs.

<prelude>:1459

def index(other: Bytes, start: Int = …) -> Int?

The byte offset of the first occurrence of other at or after start (counted from the end when negative), or nil when there is none.

b"h\xc3\xa9llo".index(b"l")      # => 3
b"h\xc3\xa9llo".index(b"l", 4)   # => 4
b"h\xc3\xa9llo".index(b"x")      # => nil

<prelude>:1468

def index(pattern: Regexp, start: Int = …) -> Int?

The byte offset of the first match of pattern at or after start (counted from the end when negative), or nil when there is none.

<prelude>:1471

def rindex(other: Bytes) -> Int?

The byte offset of the last occurrence of other, or nil when there is none.

<prelude>:1474

def rindex(other: Bytes, start: Int) -> Int?

The byte offset of the last occurrence of other that starts at or before start (counted from the end when negative), or nil.

<prelude>:1477

def rindex(pattern: Regexp) -> Int?

The byte offset of the last match of pattern, or nil when there is none.

<prelude>:1480

def rindex(pattern: Regexp, start: Int) -> Int?

The byte offset of the last match of pattern that starts at or before start (counted from the end when negative), or nil.

<prelude>:1483

def split(separator: Bytes, limit: Int = …) -> Array[Bytes]

The pieces between the occurrences of separator, as String#split.

Trailing empty pieces are dropped unless limit is negative; a positive limit gives at most that many pieces, the last holding the rest. An empty separator splits into single bytes, and empty bytes give no piece.

b"a,b,,".split(b",")             # => [b"a", b"b"]
b"a,b,,".split(b",", -1)         # => [b"a", b"b", b"", b""]
b"a,b,c".split(b",", 2)          # => [b"a", b"b,c"]

<prelude>:1496

def split(separator: Regexp, limit: Int = …) -> Array[Bytes]

The pieces between the matches of separator, as String#split with a Regexp: limit as with a Bytes separator, and the groups of a match after the piece before it.

b"a1b".split(/(\d)/)             # => [b"a", b"1", b"b"]

<prelude>:1504

def partition(separator: Bytes) -> [Bytes, Bytes, Bytes]

The bytes before the first occurrence of separator, the separator, and the bytes after it; [self, b"", b""] when it does not occur.

<prelude>:1507

def partition(pattern: Regexp) -> [Bytes, Bytes, Bytes]

The bytes before the first match of pattern, the match, and the bytes after it; [self, b"", b""] when it does not match.

<prelude>:1510

def rpartition(separator: Bytes) -> [Bytes, Bytes, Bytes]

The bytes before the last occurrence of separator, the separator, and the bytes after it; [b"", b"", self] when it does not occur.

<prelude>:1513

def rpartition(pattern: Regexp) -> [Bytes, Bytes, Bytes]

The bytes before the last match of pattern, the match, and the bytes after it; [b"", b"", self] when it does not match.

<prelude>:1516

def =~(pattern: Regexp) -> Int?

The byte offset of the first match of pattern, or nil when it does not match.

<prelude>:1519

def match(pattern: Regexp) -> Bytes::MatchData?

The first match of pattern, or nil when it does not match.

<prelude>:1521

def match?(pattern: Regexp) -> Bool

Whether pattern matches somewhere in the bytes.

A Regexp matches bytes byte by byte: \w, \d and \s are ASCII, so the UTF-8 bytes of é are no word character.

b"h\xc3\xa9".match?(/\xC3/)      # => true
b"\xc3\xa9".match?(/\w/)         # => false

<prelude>:1531

def matches(pattern: Regexp) -> Array[Bytes::MatchData]

Every match of pattern, first to last.

<prelude>:1533

def scan(pattern: Regexp) -> Array[Bytes]

The bytes of every match of pattern, first to last: the whole matches, even when the pattern has groups (#matches gives the groups).

b"a1b2".scan(/[a-z](\d)/)        # => [b"a1", b"b2"]

<prelude>:1540

def scan(pattern: Regexp, &: (Bytes) -> Void) -> Void

Calls the block with the bytes of every match of pattern, first to last.

<prelude>:1543

def scan(pattern: Regexp, &: (Bytes, Bytes::MatchData) -> Void) -> Void

Calls the block with the bytes and the Bytes::MatchData of every match of pattern, first to last.

<prelude>:1546

def sub(pattern: Bytes, replacement: Bytes) -> Bytes

The bytes with the first occurrence of pattern replaced by replacement, read as String#sub reads it: \0 (or \&) is the match, \1 to \9 and \k<name> are groups, \\ is a backslash.

b"aaa".sub(b"a", b"<\\0>")      # => b"<a>aa"

<prelude>:1554

def sub(pattern: Regexp, replacement: Bytes) -> Bytes

The bytes with the first match of pattern replaced by replacement, read as String#sub reads it (\0, \1, \k<name> ...).

<prelude>:1557

def sub(pattern: Bytes, &: (Bytes) -> Bytes) -> Bytes

The bytes with the first occurrence of pattern replaced by the block's result, called with it.

<prelude>:1560

def sub(pattern: Regexp, &: (Bytes) -> Bytes) -> Bytes

The bytes with the first match of pattern replaced by the block's result, called with the match.

<prelude>:1563

def sub(pattern: Regexp, &: (Bytes, Bytes::MatchData) -> Bytes) -> Bytes

The bytes with the first match of pattern replaced by the block's result, called with the match and its Bytes::MatchData.

<prelude>:1566

def gsub(pattern: Bytes, replacement: Bytes) -> Bytes

The bytes with every occurrence of pattern replaced by replacement, read as #sub reads it.

<prelude>:1569

def gsub(pattern: Regexp, replacement: Bytes) -> Bytes

The bytes with every match of pattern replaced by replacement, read as #sub reads it.

b"a1b22".gsub(/\d+/, b"#")       # => b"a#b#"

<prelude>:1576

def gsub(pattern: Bytes, &: (Bytes) -> Bytes) -> Bytes

The bytes with every occurrence of pattern replaced by the block's result, called with it.

<prelude>:1579

def gsub(pattern: Regexp, &: (Bytes) -> Bytes) -> Bytes

The bytes with every match of pattern replaced by the block's result, called with the match.

<prelude>:1582

def gsub(pattern: Regexp, &: (Bytes, Bytes::MatchData) -> Bytes) -> Bytes

The bytes with every match of pattern replaced by the block's result, called with the match and its Bytes::MatchData.

<prelude>:1585

def gsub(pattern: Regexp, replacements: Hash[Bytes, Bytes]) -> Bytes

The bytes with every match of pattern replaced by its value in replacements; a match that is no key there is removed.

b"lol".gsub(/[lo]/, {b"l" => b"1"})   # => b"11"

<prelude>:1592