primitives.bytes_

Module nu.forms.primitives.bytes_.

Bytes - bytes interface.

Bytes

Bytes interface. Sliceable + comparable + logical + bytes methods.

Bytes()

Path nu.forms.Bytes. Kind ScalarQuery, sort scalar_query, cardinality scalar.

Notes

• Indexing with [] yields Int, the byte's value 0-255. Slicing with [:] yields Bytes.
• decode and hex_ are the only two methods that leave bytes: decode produces a Str, hex_ produces a Str of hex digits. Every other method stays in Bytes.
• Comparison operators yield Bool, ordering lexicographically by byte value, same as Python's bytes ordering.
• Logical operators are the named forms and_, or_, not_.

Example

nu.run(nu.Bytes(b"hi") + nu.Bytes(b" there"))[0]

b'hi there'

Methods

a + b

Concatenation of self and other.

Builds Bytes.

Arguments

Yields

The concatenation. EMPTY when either operand is EMPTY.

Example

nu.run(nu.Bytes(b"foo") + nu.Bytes(b"bar"))[0]

b'foobar'

a[key]

Byte at an index, or a sub-range by slice.

Builds Bytes | Int.

Arguments

Yields

The byte's value 0-255 as Int for a single index. A new Bytes for a slice. EMPTY when self is EMPTY. Raises when the index is out of range.

Examples

nu.run(nu.Bytes(b"hello")[1])[0]

101

nu.run(nu.Bytes(b"hello")[1:3])[0]

b'el'

.len()

Length of self in bytes.

Builds Int.

Yields

The length as Int. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abc").len())[0]

3

.contains(item)

Substring test: item in self.

Builds Bool.

Arguments

Yields

True when item occurs in self, False otherwise. EMPTY when either operand is EMPTY.

Notes

• Named because Python's in must return a native bool.
• An int item tests for that byte value, as Python's in does on bytes.

Example

nu.run(nu.Bytes(b"abc").contains(b"b"))[0]

True

a > b

Self strictly greater than other.

Builds Bool.

Arguments

Yields

True when self sorts after other, False otherwise. EMPTY when either operand is EMPTY.

Example

nu.run(nu.Bytes(b"b") > nu.Bytes(b"a"))[0]

True

a < b

Self strictly less than other.

Builds Bool.

Arguments

Yields

True when self sorts before other, False otherwise. EMPTY when either operand is EMPTY.

Example

nu.run(nu.Bytes(b"a") < nu.Bytes(b"b"))[0]

True

a >= b

Self greater than or equal to other.

Builds Bool.

Arguments

Yields

True when self sorts after or equal to other, False otherwise. EMPTY when either operand is EMPTY.

Example

nu.run(nu.Bytes(b"a") >= nu.Bytes(b"a"))[0]

True

a <= b

Self less than or equal to other.

Builds Bool.

Arguments

Yields

True when self sorts before or equal to other, False otherwise. EMPTY when either operand is EMPTY.

Example

nu.run(nu.Bytes(b"a") <= nu.Bytes(b"b"))[0]

True

a == b

Self equal to other by value.

Builds Bool.

Arguments

Yields

True when the byte values are equal, False otherwise. EMPTY when either operand is EMPTY.

Notes

• Value equality, not identity. Use is_ for identity.

Example

nu.run(nu.Bytes(b"abc") == nu.Bytes(b"abc"))[0]

True

a != b

Self not equal to other by value.

Builds Bool.

Arguments

Yields

True when the byte values differ, False otherwise. EMPTY when either operand is EMPTY.

Notes

• Value inequality, not identity. Use is_ for identity.

Example

nu.run(nu.Bytes(b"abc") != nu.Bytes(b"xyz"))[0]

True

.is_(other)

Identity comparison: self is other.

Builds Bool.

Arguments

Yields

True when self and other evaluate to the same Python object, False otherwise.

Notes

• Object identity, not value equality. For value comparison use == instead.

Example

nu.run(nu.Bytes(b"abc").is_(b"abc"))[0]

True

.and_(other)

Logical AND of self and other.

Builds Bool.

Arguments

Yields

True when both operands are truthy, False otherwise. An EMPTY operand counts as false.

Notes

• Short-circuits like Python: the right operand is only evaluated when the left does not already decide the result.

Example

nu.run(nu.Bytes(b"").and_(nu.Bytes(b"x")))[0]

False

.or_(other)

Logical OR of self and other.

Builds Bool.

Arguments

Yields

True when either operand is truthy, False otherwise. An EMPTY operand counts as false.

Notes

• Short-circuits like Python: the right operand is only evaluated when the left does not already decide the result.

Example

nu.run(nu.Bytes(b"x").or_(nu.Bytes(b"")))[0]

True

.not_()

Logical NOT of self.

Builds Bool.

Yields

True when self is empty, False otherwise. EMPTY when self is EMPTY.

Notes

• Empty bytes yields True, every other value yields False.

Example

nu.run(nu.Bytes(b"").not_())[0]

True

.bool_()

Cast self to Bool.

Builds Bool.

Yields

True when self is non-empty, False when self is empty. EMPTY when self is EMPTY.

Notes

• Empty bytes becomes False, every other value becomes True, matching Python's truthiness rule.

Example

nu.run(nu.Bytes(b"hi").bool_())[0]

True

.decode(encoding='utf-8')

Decode self to a string using the given encoding.

Builds Str.

Arguments

Yields

The decoded Str. EMPTY when self is EMPTY. Raises when the bytes are not valid under the encoding, or when the encoding name is unknown.

Notes

• This is where Bytes crosses into Str. Every other method on this class stays in bytes.

Example

nu.run(nu.Bytes(b"hi there").decode())[0]

'hi there'

.hex_()

Hex string of self, two digits per byte.

Builds Str.

Yields

The lowercase hex digits, no separators. EMPTY when self is EMPTY.

Notes

• The other place, besides decode, where Bytes crosses into Str.

Example

nu.run(nu.Bytes(b"\xff\x00").hex_())[0]

'ff00'

.upper()

Self with ASCII letters uppercased.

Builds Bytes.

Yields

The uppercased bytes. EMPTY when self is EMPTY.

Notes

• ASCII only. Non-ASCII bytes pass through unchanged.

Example

nu.run(nu.Bytes(b"Hi").upper())[0]

b'HI'

.lower()

Self with ASCII letters lowercased.

Builds Bytes.

Yields

The lowercased bytes. EMPTY when self is EMPTY.

Notes

• ASCII only. Non-ASCII bytes pass through unchanged.

Example

nu.run(nu.Bytes(b"Hi").lower())[0]

b'hi'

.strip(chars=None)

Self with leading and trailing bytes removed.

Builds Bytes.

Arguments

Yields

The stripped bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"  hi  ").strip())[0]

b'hi'

.lstrip(chars=None)

Self with leading bytes removed.

Builds Bytes.

Arguments

Yields

The stripped bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"  hi  ").lstrip())[0]

b'hi  '

.rstrip(chars=None)

Self with trailing bytes removed.

Builds Bytes.

Arguments

Yields

The stripped bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"  hi  ").rstrip())[0]

b'  hi'

.split_bytes(sep=None, maxsplit=-1)

Self split into a List of Bytes on sep.

Builds List.

Arguments

Yields

The pieces as a List of Bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"a,b,c").split_bytes(b","))[0]

[b'a', b'b', b'c']

.find_bytes(sub, start=0, end=None)

Lowest index of sub in self, or -1 if absent.

Builds Int.

Arguments

Yields

The index of the first match, or -1 when sub is not found. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abcabc").find_bytes(b"bc"))[0]

1

.count_bytes(sub)

Number of non-overlapping occurrences of sub in self.

Builds Int.

Arguments

Yields

The count. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abcabc").count_bytes(b"bc"))[0]

2

.startswith(prefix)

Self starts with prefix.

Builds Bool.

Arguments

Yields

True when self starts with prefix, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"hello").startswith(b"he"))[0]

True

.endswith(suffix)

Self ends with suffix.

Builds Bool.

Arguments

Yields

True when self ends with suffix, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"hello").endswith(b"lo"))[0]

True

.replace(old, new, count=-1)

Self with occurrences of old replaced by new.

Builds Bytes.

Arguments

Yields

The replaced bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"aXbXc").replace(b"X", b"-"))[0]

b'a-b-c'

.removeprefix(prefix)

Self with prefix removed if present.

Builds Bytes.

Arguments

Yields

Self without the leading prefix, or self unchanged when the prefix is not present. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"prefoo").removeprefix(b"pre"))[0]

b'foo'

.removesuffix(suffix)

Self with suffix removed if present.

Builds Bytes.

Arguments

Yields

Self without the trailing suffix, or self unchanged when the suffix is not present. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"foobar").removesuffix(b"bar"))[0]

b'foo'

.translate(table, delete=b'')

Self translated through a 256-byte table, with bytes in delete dropped first.

Builds Bytes.

Arguments

Yields

The translated bytes. EMPTY when self is EMPTY. Raises when table is not exactly 256 bytes long.

Example

nu.run(nu.Bytes(b"abc").translate(bytes.maketrans(b"ab", b"AB")))[0]

b'ABc'

.title()

Self titlecased: each word's first cased byte upper, the rest lower.

Builds Bytes.

Yields

The titlecased bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"hello world").title())[0]

b'Hello World'

.capitalize()

Self with the first byte uppercased and the rest lowercased.

Builds Bytes.

Yields

The capitalized bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"hello world").capitalize())[0]

b'Hello world'

.swapcase()

Self with uppercase and lowercase bytes swapped.

Builds Bytes.

Yields

The case-swapped bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"Hello").swapcase())[0]

b'hELLO'

.rsplit_bytes(sep=None, maxsplit=-1)

Self split into a List of Bytes on sep, counting maxsplit from the right.

Builds List.

Arguments

Yields

The pieces as a List of Bytes. EMPTY when self is EMPTY.

Notes

• Only differs from split_bytes when maxsplit limits the split count; the pieces themselves are the same bytes either way.

Example

nu.run(nu.Bytes(b"a,b,c").rsplit_bytes(b",", 1))[0]

[b'a,b', b'c']

.splitlines(keepends=False)

Self split into a List of Bytes at line boundaries.

Builds List.

Arguments

Yields

The lines as a List of Bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"a\nb\nc").splitlines())[0]

[b'a', b'b', b'c']

.partition(sep)

Self split around the first occurrence of sep.

Builds Tuple.

Arguments

Yields

A 3-tuple of (before, sep, after). When sep is not found, (self, b"", b""). EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"key=value").partition(b"="))[0]

(b'key', b'=', b'value')

.rpartition(sep)

Self split around the last occurrence of sep.

Builds Tuple.

Arguments

Yields

A 3-tuple of (before, sep, after). When sep is not found, (b"", b"", self). EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"a=b=c").rpartition(b"="))[0]

(b'a=b', b'=', b'c')

.rfind_bytes(sub, start=0, end=None)

Highest index of sub in self, or -1 if absent.

Builds Int.

Arguments

Yields

The index of the last match, or -1 when sub is not found. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abcabc").rfind_bytes(b"bc"))[0]

4

.index_bytes(sub, start=0, end=None)

Lowest index of sub in self.

Builds Int.

Arguments

Yields

The index of the first match. EMPTY when self is EMPTY or when sub is not found.

Notes

• Like find_bytes but EMPTY instead of -1 when sub is not found, where Python's index raises ValueError.

Example

nu.run(nu.Bytes(b"abc").index_bytes(b"b"))[0]

1

.rindex_bytes(sub, start=0, end=None)

Highest index of sub in self.

Builds Int.

Arguments

Yields

The index of the last match. EMPTY when self is EMPTY or when sub is not found.

Notes

• Like rfind_bytes but EMPTY instead of -1 when sub is not found, where Python's rindex raises ValueError.

Example

nu.run(nu.Bytes(b"abcabc").rindex_bytes(b"bc"))[0]

4

.isascii()

Self has only ASCII bytes.

Builds Bool.

Yields

True when every byte is ASCII, False otherwise. EMPTY when self is EMPTY.

Notes

• Empty bytes is True.

Example

nu.run(nu.Bytes(b"hello").isascii())[0]

True

.isdigit()

Self has only ASCII digit bytes, and at least one.

Builds Bool.

Yields

True when every byte is an ASCII digit and self is non-empty, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"123").isdigit())[0]

True

.isalpha()

Self has only ASCII letter bytes, and at least one.

Builds Bool.

Yields

True when every byte is an ASCII letter and self is non-empty, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abc").isalpha())[0]

True

.isalnum()

Self has only ASCII alphanumeric bytes, and at least one.

Builds Bool.

Yields

True when every byte is an ASCII letter or digit and self is non-empty, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abc123").isalnum())[0]

True

.isspace()

Self has only ASCII whitespace bytes, and at least one.

Builds Bool.

Yields

True when every byte is ASCII whitespace and self is non-empty, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"  ").isspace())[0]

True

.istitle()

Self is titlecased, with at least one cased byte.

Builds Bool.

Yields

True when self follows title case, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"Hello World").istitle())[0]

True

.isupper()

Self has all cased bytes uppercase, and at least one cased byte.

Builds Bool.

Yields

True when every cased byte is uppercase, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"ABC").isupper())[0]

True

.islower()

Self has all cased bytes lowercase, and at least one cased byte.

Builds Bool.

Yields

True when every cased byte is lowercase, False otherwise. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"abc").islower())[0]

True

.center(width, fillbyte=b' ')

Self centered in a field of width, padded with fillbyte.

Builds Bytes.

Arguments

Yields

The padded bytes. EMPTY when self is EMPTY. Raises when fillbyte is not exactly one byte.

Example

nu.run(nu.Bytes(b"hi").center(6))[0]

b'  hi  '

.ljust(width, fillbyte=b' ')

Self left-justified in a field of width, padded with fillbyte.

Builds Bytes.

Arguments

Yields

The padded bytes. EMPTY when self is EMPTY. Raises when fillbyte is not exactly one byte.

Example

nu.run(nu.Bytes(b"hi").ljust(5))[0]

b'hi   '

.rjust(width, fillbyte=b' ')

Self right-justified in a field of width, padded with fillbyte.

Builds Bytes.

Arguments

Yields

The padded bytes. EMPTY when self is EMPTY. Raises when fillbyte is not exactly one byte.

Example

nu.run(nu.Bytes(b"hi").rjust(5))[0]

b'   hi'

.zfill(width)

Self padded with leading zero bytes to width.

Builds Bytes.

Arguments

Yields

The zero-padded bytes. EMPTY when self is EMPTY.

Notes

• A leading sign byte (+ or -), if present, stays first and the zeros go after it.

Example

nu.run(nu.Bytes(b"42").zfill(5))[0]

b'00042'

.expandtabs(tabsize=8)

Self with tab bytes expanded to spaces.

Builds Bytes.

Arguments

Yields

The expanded bytes. EMPTY when self is EMPTY.

Example

nu.run(nu.Bytes(b"a\tb").expandtabs(4))[0]

b'a   b'

.join(iterable)

Self used as separator between the elements of iterable.

Builds Bytes.

Arguments

Yields

The joined bytes. EMPTY when self is EMPTY. Raises when any element is not bytes.

Example

nu.run(nu.Bytes(b",").join([b"a", b"b", b"c"]))[0]

b'a,b,c'

Inherited methods

From nu.lang.forms.Form: