primitives.str_

Module nu.forms.primitives.str_.

Str - string interface.

Str

String interface. Addable + sliceable + comparable + logical + string methods.

Str()

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

Notes

• + concatenates; there's no numeric arithmetic on Str.
• Comparison operators compare lexicographically, Python str ordering, and yield Bool. Chained comparisons like a > b > c do not build a single term; write them as And(a > b, b > c).
• Logical operators are the named forms and_, or_, not_, and coerce by truthiness: the empty string is False, every other string is True.
• Most string methods degrade to INVALID on failure rather than raising at evaluation time (a missing index/rindex match, a multi-character fillchar, an unencodable character, a missing format_map key). Indexing with an out-of-range int is the exception: it raises, matching Python.

Example

nu.run(nu.Str("ab") + nu.Str("cd"))[0]

'abcd'

Methods

a + b

Concatenation of self and other.

Builds Str.

Arguments

Yields

The concatenation. INVALID when either operand is not a Str or is a sentinel.

Example

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

'foobar'

a[key]

Character at an int index, or substring for a slice.

Builds Str.

Arguments

Yields

The single character for an int key, the substring for a slice. INVALID when self is a sentinel or not a Str.

Notes

• An out-of-range int index raises at evaluation time, matching Python. A slice never raises; out-of-range bounds are clamped like Python slicing, so s[10:20] on a shorter string yields the empty string rather than erroring.
• Negative indices and negative slice bounds work as in Python.

Examples

nu.run(nu.Str("hello")[1])[0]

'e'

nu.run(nu.Str("hello")[1:4])[0]

'ell'

a > b

Self strictly greater than other, lexicographically.

Builds Bool.

Arguments

Yields

True when self sorts after other, False otherwise. INVALID when either operand is not a Str or is a sentinel.

Example

nu.run(nu.Str("banana") > nu.Str("apple"))[0]

True

a < b

Self strictly less than other, lexicographically.

Builds Bool.

Arguments

Yields

True when self sorts before other, False otherwise. INVALID when either operand is not a Str or is a sentinel.

Example

nu.run(nu.Str("apple") < nu.Str("banana"))[0]

True

a >= b

Self greater than or equal to other, lexicographically.

Builds Bool.

Arguments

Yields

True when self sorts after or equal to other, False otherwise. INVALID when either operand is not a Str or is a sentinel.

Example

nu.run(nu.Str("apple") >= nu.Str("apple"))[0]

True

a <= b

Self less than or equal to other, lexicographically.

Builds Bool.

Arguments

Yields

True when self sorts before or equal to other, False otherwise. INVALID when either operand is not a Str or is a sentinel.

Example

nu.run(nu.Str("apple") <= nu.Str("banana"))[0]

True

a == b

Self equal to other by value.

Builds Bool.

Arguments

Yields

True when the strings compare equal, False otherwise. INVALID when either operand is not a Str or is a sentinel.

Notes

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

Example

nu.run(nu.Str("hi") == nu.Str("hi"))[0]

True

a != b

Self not equal to other by value.

Builds Bool.

Arguments

Yields

True when the strings differ, False otherwise. INVALID when either operand is not a Str or is a sentinel.

Notes

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

Example

nu.run(nu.Str("hi") != nu.Str("bye"))[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 scalar comparison use == instead.
• Python interns short/literal strings, so distinct Str literals with equal text can still test identical.

Example

nu.run(nu.Str("abc").is_("abc"))[0]

True

.and_(other)

Logical AND of self and other.

Builds Bool.

Arguments

Yields

True when both operands are truthy, False otherwise. INVALID when either operand is a sentinel.

Notes

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

Example

nu.run(nu.Str("hi").and_(nu.Str("")))[0]

False

.or_(other)

Logical OR of self and other.

Builds Bool.

Arguments

Yields

True when either operand is truthy, False otherwise. INVALID when either operand is a sentinel.

Notes

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

Example

nu.run(nu.Str("").or_(nu.Str("hi")))[0]

True

.not_()

Logical NOT of self.

Builds Bool.

Yields

True when self is the empty string, False otherwise. INVALID when self is a sentinel.

Notes

• The empty string yields True, every other string yields False.

Example

nu.run(nu.Str("").not_())[0]

True

.bool_()

Cast self to Bool.

Builds Bool.

Yields

True when self is non-empty, False when self is empty. INVALID when self is a sentinel.

Notes

• The empty string becomes False, every other string becomes True, matching Python's truthiness rule.

Example

nu.run(nu.Str("hi").bool_())[0]

True

.upper()

Self converted to uppercase.

Builds Str.

Yields

The uppercased string. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("Hello World").upper())[0]

'HELLO WORLD'

.lower()

Self converted to lowercase.

Builds Str.

Yields

The lowercased string. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("Hello World").lower())[0]

'hello world'

.title()

Self converted to title case.

Builds Str.

Yields

The titlecased string. INVALID when self is a sentinel or not a Str.

Example

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

'Hello World'

.capitalize()

Self with only the first character capitalized.

Builds Str.

Yields

The capitalized string. INVALID when self is a sentinel or not a Str.

Notes

• Every character after the first is lowercased, matching Python's str.capitalize.

Example

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

'Hello world'

.swapcase()

Self with uppercase and lowercase characters swapped.

Builds Str.

Yields

The case-swapped string. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("Hello World").swapcase())[0]

'hELLO wORLD'

.casefold()

Self folded for aggressive, caseless matching.

Builds Str.

Yields

The casefolded string. INVALID when self is a sentinel or not a Str.

Notes

• Stronger than lower: handles cases lower misses, like the German ß folding to ss.

Example

nu.run(nu.Str("Straße").casefold())[0]

'strasse'

.strip(chars=None)

Self with leading and trailing characters removed.

Builds Str.

Arguments

Yields

The stripped string. INVALID when self is a sentinel or not a Str.

Examples

nu.run(nu.Str("  hi  ").strip())[0]

'hi'

nu.run(nu.Str("xxhixx").strip("x"))[0]

'hi'

.lstrip(chars=None)

Self with leading characters removed.

Builds Str.

Arguments

Yields

The left-stripped string. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("  hi  ").lstrip())[0]

'hi  '

.rstrip(chars=None)

Self with trailing characters removed.

Builds Str.

Arguments

Yields

The right-stripped string. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("  hi  ").rstrip())[0]

'  hi'

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

Self split into a list on sep, from the left.

Builds List.

Arguments

Yields

The list of pieces. INVALID when self is a sentinel or not a Str.

Examples

nu.run(nu.Str("a,b,c").split(","))[0]

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

nu.run(nu.Str("a,b,c").split(",", 1))[0]

['a', 'b,c']

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

Self split into a list on sep, from the right.

Builds List.

Arguments

Yields

The list of pieces. INVALID when self is a sentinel or not a Str.

Notes

• Only differs from split when maxsplit is bounded: the splits are taken starting from the right end of the string.

Example

nu.run(nu.Str("a,b,c").rsplit(",", 1))[0]

['a,b', 'c']

.splitlines(keepends=False)

Self split into a list at line boundaries.

Builds List.

Arguments

Yields

The list of lines. INVALID when self is a sentinel or not a Str.

Example

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

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

.partition(sep)

Self split around the first occurrence of sep into a 3-tuple.

Builds Tuple.

Arguments

Yields

The 3-tuple of pieces. INVALID when self is a sentinel, not a Str, or sep is empty.

Notes

• The 3-tuple is always (before, sep, after). When sep is not found, that's (self, "", "").

Example

nu.run(nu.Str("a,b,c").partition(","))[0]

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

.rpartition(sep)

Self split around the last occurrence of sep into a 3-tuple.

Builds Tuple.

Arguments

Yields

The 3-tuple of pieces. INVALID when self is a sentinel, not a Str, or sep is empty.

Notes

• The 3-tuple is always (before, sep, after). When sep is not found, that's ("", "", self).

Example

nu.run(nu.Str("a,b,c").rpartition(","))[0]

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

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

Lowest index in self where sub is found, searching from the left.

Builds Int.

Arguments

Yields

The lowest matching index, or -1 when sub is not found. INVALID when self is a sentinel or not a Str.

Examples

nu.run(nu.Str("hello world").find("o"))[0]

4

nu.run(nu.Str("hello world").find("z"))[0]

-1

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

Highest index in self where sub is found, searching from the right.

Builds Int.

Arguments

Yields

The highest matching index, or -1 when sub is not found. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("hello world").rfind("o"))[0]

7

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

Lowest index in self where sub is found, searching from the left.

Builds Int.

Arguments

Yields

The lowest matching index. INVALID when self is a sentinel, not a Str, or sub is not found.

Notes

• Unlike Python's str.index, a missing sub does not raise: it yields INVALID instead. Use find if -1 on a miss is the behaviour you want.

Example

nu.run(nu.Str("hello world").index("o"))[0]

4

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

Highest index in self where sub is found, searching from the right.

Builds Int.

Arguments

Yields

The highest matching index. INVALID when self is a sentinel, not a Str, or sub is not found.

Notes

• Unlike Python's str.rindex, a missing sub does not raise: it yields INVALID instead. Use rfind if -1 on a miss is the behaviour you want.

Example

nu.run(nu.Str("hello world").rindex("o"))[0]

7

.count_substring(sub)

Count of non-overlapping occurrences of sub in self.

Builds Int.

Arguments

Yields

The occurrence count. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("banana").count_substring("an"))[0]

2

.startswith(prefix)

Whether self starts with prefix.

Builds Bool.

Arguments

Yields

True when self starts with prefix, False otherwise. INVALID when self is a sentinel or not a Str.

Example

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

True

.endswith(suffix)

Whether self ends with suffix.

Builds Bool.

Arguments

Yields

True when self ends with suffix, False otherwise. INVALID when self is a sentinel or not a Str.

Example

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

True

.isdigit()

Whether every character in self is a digit.

Builds Bool.

Yields

True when self is non-empty and every character is a digit, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("123").isdigit())[0]

True

.isalpha()

Whether every character in self is alphabetic.

Builds Bool.

Yields

True when self is non-empty and every character is alphabetic, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("abc").isalpha())[0]

True

.isalnum()

Whether every character in self is alphanumeric.

Builds Bool.

Yields

True when self is non-empty and every character is alphanumeric, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("abc123").isalnum())[0]

True

.isspace()

Whether every character in self is whitespace.

Builds Bool.

Yields

True when self is non-empty and every character is whitespace, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("   ").isspace())[0]

True

.isnumeric()

Whether every character in self is numeric.

Builds Bool.

Yields

True when self is non-empty and every character is numeric, False otherwise. INVALID when self is a sentinel or not a Str.

Notes

• Broader than isdigit: also true for characters like fractions and Unicode numerals that isdigit rejects.

Example

nu.run(nu.Str("123").isnumeric())[0]

True

.isdecimal()

Whether every character in self is a decimal character.

Builds Bool.

Yields

True when self is non-empty and every character is decimal, False otherwise. INVALID when self is a sentinel or not a Str.

Notes

• Narrower than isnumeric: only characters that can form base-10 numbers qualify.

Example

nu.run(nu.Str("123").isdecimal())[0]

True

.isidentifier()

Whether self is a valid Python identifier.

Builds Bool.

Yields

True when self would be a legal Python identifier, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("my_var").isidentifier())[0]

True

.isprintable()

Whether every character in self is printable.

Builds Bool.

Yields

True when every character is printable, False otherwise. INVALID when self is a sentinel or not a Str.

Notes

• The empty string is printable; it's the presence of non-printable characters (like control characters) that makes this False.

Example

nu.run(nu.Str("abc").isprintable())[0]

True

.istitle()

Whether self is titlecased.

Builds Bool.

Yields

True when self is non-empty and titlecased (each word starts uppercase, the rest lowercase), False otherwise. INVALID when self is a sentinel or not a Str.

Example

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

True

.isupper()

Whether every cased character in self is uppercase.

Builds Bool.

Yields

True when self has at least one cased character and all of them are uppercase, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("ABC").isupper())[0]

True

.islower()

Whether every cased character in self is lowercase.

Builds Bool.

Yields

True when self has at least one cased character and all of them are lowercase, False otherwise. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("abc").islower())[0]

True

.isascii()

Whether every character in self is ASCII.

Builds Bool.

Yields

True when every character is ASCII, False otherwise. INVALID when self is a sentinel or not a Str.

Notes

• Unlike the other is* checks, the empty string yields True here rather than False.

Example

nu.run(nu.Str("").isascii())[0]

True

.center(width, fillchar=' ')

Self centered in a field of the given width.

Builds Str.

Arguments

Yields

The centered string. INVALID when self is a sentinel, not a Str, or fillchar is not a single character.

Notes

• fillchar must be exactly one character; anything else yields INVALID rather than raising.

Example

nu.run(nu.Str("hi").center(6, "*"))[0]

'**hi**'

.ljust(width, fillchar=' ')

Self left-justified in a field of the given width.

Builds Str.

Arguments

Yields

The left-justified string. INVALID when self is a sentinel, not a Str, or fillchar is not a single character.

Notes

• fillchar must be exactly one character; anything else yields INVALID rather than raising.

Example

nu.run(nu.Str("hi").ljust(6, "*"))[0]

'hi****'

.rjust(width, fillchar=' ')

Self right-justified in a field of the given width.

Builds Str.

Arguments

Yields

The right-justified string. INVALID when self is a sentinel, not a Str, or fillchar is not a single character.

Notes

• fillchar must be exactly one character; anything else yields INVALID rather than raising.

Example

nu.run(nu.Str("hi").rjust(6, "*"))[0]

'****hi'

.zfill(width)

Self padded with leading zeros to the given width.

Builds Str.

Arguments

Yields

The zero-filled string. INVALID when self is a sentinel or not a Str.

Notes

• A leading sign (+ or -) stays in front of the zeros rather than being padded over, matching Python's str.zfill.

Example

nu.run(nu.Str("-42").zfill(5))[0]

'-0042'

.expandtabs(tabsize=8)

Self with tab characters expanded to spaces.

Builds Str.

Arguments

Yields

The expanded string. INVALID when self is a sentinel or not a Str.

Example

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

'a   b'

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

Self with occurrences of old replaced by new.

Builds Str.

Arguments

Yields

The replaced string. INVALID when self is a sentinel or not a Str.

Examples

nu.run(nu.Str("hello world").replace("o", "0"))[0]

'hell0 w0rld'

nu.run(nu.Str("hello world").replace("o", "0", 1))[0]

'hell0 world'

.removeprefix(prefix)

Self with the given prefix removed if present.

Builds Str.

Arguments

Yields

The string with prefix removed. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("hello.txt").removeprefix("hello"))[0]

'.txt'

.removesuffix(suffix)

Self with the given suffix removed if present.

Builds Str.

Arguments

Yields

The string with suffix removed. INVALID when self is a sentinel or not a Str.

Example

nu.run(nu.Str("hello.txt").removesuffix(".txt"))[0]

'hello'

.translate(table)

Self with characters mapped through a translation table.

Builds Str.

Arguments

Yields

The translated string. INVALID when self is a sentinel, not a Str, or table is malformed.

Notes

• A malformed table (bad ordinal, bad replacement type) yields INVALID rather than raising.

Example

nu.run(nu.Str("hello").translate({104: 72}))[0]

'Hello'

.format_map(mapping)

Self formatted with {field} placeholders filled from mapping.

Builds Str.

Arguments

Yields

The formatted string. INVALID when self is a sentinel, not a Str, or formatting fails.

Notes

• A missing field, or any other formatting error, yields INVALID rather than raising.

Example

nu.run(nu.Str("{name} is {age}").format_map({"name": "Nu", "age": 1}))[0]

'Nu is 1'

.encode(encoding='utf-8')

Self encoded to Bytes.

Builds Bytes.

Arguments

Yields

The encoded bytes. INVALID when self is a sentinel, not a Str, or encoding fails.

Notes

• A character that can't be represented in the given encoding, or an unknown encoding name, yields INVALID rather than raising.

Example

nu.run(nu.Str("hello").encode())[0]

b'hello'

.join(iterable)

Elements of iterable joined together with self as separator.

Builds Str.

Arguments

Yields

The joined string. INVALID when self is a sentinel, not a Str, or iterable contains a non-string element.

Notes

• A non-string element yields INVALID rather than raising.

Example

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

'a, b, c'

Inherited methods

From nu.lang.forms.Form: