struct

String

Represents a mutable string.

Aliases

ASCII_LOWERCASE = "abcdefghijklmnopqrstuvwxyz":
ASCII_UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ":
ASCII_LETTERS = __add__("abcdefghijklmnopqrstuvwxyz", "ABCDEFGHIJKLMNOPQRSTUVWXYZ"):
DIGITS = "0123456789":
HEX_DIGITS = __add__(__add__("0123456789", "abcdef"), "ABCDEF"):
OCT_DIGITS = "01234567":
PUNCTUATION = "!\22#$%&'()*+,-./:;<=>?@[\\]^_{|}~"`:
PRINTABLE = __add__(__add__(__add__("0123456789", __add__("abcdefghijklmnopqrstuvwxyz", "ABCDEFGHIJKLMNOPQRSTUVWXYZ")), "!\22#$%&'()*+,-./:;<=>?@[\\]^_{|}~"), " \09\0A\0D\0B\0C")`:

Implemented traits

AnyType, Boolable, CollectionElement, Comparable, Copyable, EqualityComparable, Formattable, Hashable, IntableRaising, KeyElement, Movable, Representable, Sized, Stringable, ToFormatter

Methods

`init`

__init__(inout self: Self, owned impl: List[SIMD[uint8, 1]])

Construct a string from a buffer of bytes.

The buffer must be terminated with a null byte:

var buf = List[UInt8]()
buf.append(ord('H'))
buf.append(ord('i'))
buf.append(0)
var hi = String(buf)

Args:

impl (List[SIMD[uint8, 1]]): The buffer.

__init__(inout self: Self)

Construct an uninitialized string.

__init__(inout self: Self, str: StringRef)

Construct a string from a StringRef object.

Args:

str (StringRef): The StringRef from which to construct this string object.

__init__(inout self: Self, str_slice: StringSlice[is_mutable, lifetime])

Construct a string from a string slice.

This will allocate a new string that copies the string contents from the provided string slice str_slice.

Args:

str_slice (StringSlice[is_mutable, lifetime]): The string slice from which to construct this string.

__init__(inout self: Self, literal: StringLiteral)

Constructs a String value given a constant string.

Args:

literal (StringLiteral): The input constant string.

__init__(inout self: Self, ptr: UnsafePointer[SIMD[uint8, 1], 0], len: Int)

Creates a string from the buffer. Note that the string now owns the buffer.

The buffer must be terminated with a null byte.

Args:

ptr (UnsafePointer[SIMD[uint8, 1], 0]): The pointer to the buffer.
len (Int): The length of the buffer, including the null terminator.

__init__(inout self: Self, ptr: LegacyPointer[SIMD[uint8, 1], 0], len: Int)

Creates a string from the buffer. Note that the string now owns the buffer.

The buffer must be terminated with a null byte.

Args:

ptr (LegacyPointer[SIMD[uint8, 1], 0]): The pointer to the buffer.
len (Int): The length of the buffer, including the null terminator.

__init__(inout self: Self, ptr: DTypePointer[uint8, 0], len: Int)

Creates a string from the buffer. Note that the string now owns the buffer.

The buffer must be terminated with a null byte.

Args:

ptr (DTypePointer[uint8, 0]): The pointer to the buffer.
len (Int): The length of the buffer, including the null terminator.

__init__(inout self: Self, obj: PythonObject)

Creates a string from a python object.

Args:

obj (PythonObject): A python object.

`copyinit`

__copyinit__(inout self: Self, existing: Self)

Creates a deep copy of an existing string.

Args:

existing (Self): The string to copy.

`moveinit`

__moveinit__(inout self: Self, owned existing: Self)

Move the value of a string.

Args:

existing (Self): The string to move.

`bool`

__bool__(self: Self) -> Bool

Checks if the string is not empty.

Returns:

True if the string length is greater than zero, and False otherwise.

`getitem`

__getitem__(self: Self, idx: Int) -> Self

Gets the character at the specified position.

Args:

idx (Int): The index value.

Returns:

A new string containing the character at the specified position.

__getitem__(self: Self, span: Slice) -> Self

Gets the sequence of characters at the specified positions.

Args:

span (Slice): A slice that specifies positions of the new substring.

Returns:

A new string containing the string at the specified positions.

`lt`

__lt__(self: Self, rhs: Self) -> Bool

Compare this String to the RHS using LT comparison.

Args:

rhs (Self): The other String to compare against.

Returns:

True if this String is strictly less than the RHS String and False otherwise.

`le`

__le__(self: Self, rhs: Self) -> Bool

Compare this String to the RHS using LE comparison.

Args:

rhs (Self): The other String to compare against.

Returns:

True iff this String is less than or equal to the RHS String.

`eq`

__eq__(self: Self, other: Self) -> Bool

Compares two Strings if they have the same values.

Args:

other (Self): The rhs of the operation.

Returns:

True if the Strings are equal and False otherwise.

`ne`

__ne__(self: Self, other: Self) -> Bool

Compares two Strings if they do not have the same values.

Args:

other (Self): The rhs of the operation.

Returns:

True if the Strings are not equal and False otherwise.

`gt`

__gt__(self: Self, rhs: Self) -> Bool

Compare this String to the RHS using GT comparison.

Args:

rhs (Self): The other String to compare against.

Returns:

True iff this String is strictly greater than the RHS String.

`ge`

__ge__(self: Self, rhs: Self) -> Bool

Compare this String to the RHS using GE comparison.

Args:

rhs (Self): The other String to compare against.

Returns:

True iff this String is greater than or equal to the RHS String.

`contains`

__contains__(self: Self, substr: Self) -> Bool

Returns True if the substring is contained within the current string.

Args:

substr (Self): The substring to check.

Returns:

True if the string contains the substring.

`add`

__add__(self: Self, other: Self) -> Self

Creates a string by appending another string at the end.

Args:

other (Self): The string to append.

Returns:

The new constructed string.

`mul`

__mul__(self: Self, n: Int) -> Self

Concatenates the string n times.

Args:

n (Int): The number of times to concatenate the string.

Returns:

The string concatenated n times.

`radd`

__radd__(self: Self, other: Self) -> Self

Creates a string by prepending another string to the start.

Args:

other (Self): The string to prepend.

Returns:

The new constructed string.

`iadd`

__iadd__(inout self: Self, other: Self)

Appends another string to this string.

Args:

other (Self): The string to append.

`format_sequence`

static format_sequence[*Ts: Formattable](*args: *Ts) -> Self

Construct a string by concatenating a sequence of formattable arguments.

Parameters:

*Ts (Formattable): The types of the arguments to format. Each type must be satisfy Formattable.

Args:

*args (*Ts): A sequence of formattable arguments.

Returns:

A string formed by formatting the argument sequence.

`format_to`

format_to(self: Self, inout writer: Formatter)

Formats this string to the provided formatter.

Args:

writer (Formatter): The formatter to write to.

`join`

join(self: Self, *elems: Int) -> Self

Joins the elements from the tuple using the current string as a delimiter.

Args:

*elems (Int): The input tuple.

Returns:

The joined string.

join[*Types: Stringable](self: Self, *elems: *Types) -> Self

Joins string elements using the current string as a delimiter.

Parameters:

*Types (Stringable): The types of the elements.

Args:

*elems (*Types): The input values.

Returns:

The joined string.

`unsafe_ptr`

unsafe_ptr(self: Self) -> UnsafePointer[SIMD[int8, 1], 0]

Retrieves a pointer to the underlying memory.

Note that you should use unsafe_uint8_ptr() if you need to access the pointer as we are now storing the bytes as UInt8.

See https://github.com/modularml/mojo/issues/2317 for more information.

Returns:

The pointer to the underlying memory.

`unsafe_uint8_ptr`

unsafe_uint8_ptr(self: Self) -> UnsafePointer[SIMD[uint8, 1], 0]

Retrieves a pointer to the underlying memory.

Returns:

The pointer to the underlying memory.

`as_bytes`

as_bytes(self: Self) -> List[SIMD[uint8, 1]]

Retrieves the underlying byte sequence encoding the characters in this string.

This does not include the trailing null terminator.

Returns:

A sequence containing the encoded characters stored in this string.

`as_bytes_slice`

as_bytes_slice(self: Reference[String, is_mutable, lifetime, 0]) -> Span[SIMD[uint8, 1], $0, $1]

Returns a contiguous slice of the bytes owned by this string.

This does not include the trailing null terminator.

Returns:

A contiguous slice pointing to the bytes owned by this string.

`as_string_slice`

as_string_slice(self: Reference[String, is_mutable, lifetime, 0]) -> StringSlice[$0, $1]

Returns a string slice of the data owned by this string.

Returns:

A string slice pointing to the data owned by this string.

`count`

count(self: Self, substr: Self) -> Int

Return the number of non-overlapping occurrences of substring substr in the string.

If sub is empty, returns the number of empty strings between characters which is the length of the string plus one.

Args:

substr (Self): The substring to count.

Returns:

The number of occurrences of substr.

`find`

find(self: Self, substr: Self, start: Int = 0) -> Int

Finds the offset of the first occurrence of substr starting at start. If not found, returns -1.

Args:

substr (Self): The substring to find.
start (Int): The offset from which to find.

Returns:

The offset of substr relative to the beginning of the string.

`rfind`

rfind(self: Self, substr: Self, start: Int = 0) -> Int

Finds the offset of the last occurrence of substr starting at start. If not found, returns -1.

Args:

substr (Self): The substring to find.
start (Int): The offset from which to find.

Returns:

The offset of substr relative to the beginning of the string.

`isspace`

isspace(self: Self) -> Bool

Determines whether the given String is a python whitespace String. This corresponds to Python's universal separators " \t\n\r\f\v\x1c\x1e\x85\u2028\u2029".

Returns:

True if the String is one of the whitespace characters listed above, otherwise False.

`split`

split(self: Self, sep: Self, maxsplit: Int = -1) -> List[String]

Split the string by a separator.

Examples:

# Splitting a space
_ = String("hello world").split(" ") # ["hello", "world"]
# Splitting adjacent separators
_ = String("hello,,world").split(",") # ["hello", "", "world"]
# Splitting with maxsplit
_ = String("1,2,3").split(",", 1) # ['1', '2,3']

Args:

sep (Self): The string to split on.
maxsplit (Int): The maximum amount of items to split from String. Defaults to unlimited.

Returns:

A List of Strings containing the input split by the separator.

split(self: Self, *, maxsplit: Int = -1) -> List[String]

Split the string by every Whitespace separator.

Currently only uses C style separators.

Examples:

# Splitting an empty string or filled with whitespaces
_ = String("      ").split() # []
_ = String("").split() # []

# Splitting a string with leading, trailing, and middle whitespaces
_ = String("      hello    world     ").split() # ["hello", "world"]

Args:

maxsplit (Int): The maximum amount of items to split from String. Defaults to unlimited.

Returns:

A List of Strings containing the input split by the separator.

`splitlines`

splitlines(self: Self, keepends: Bool = 0) -> List[String]

Split the string at line boundaries.

Args:

keepends (Bool): If True, line breaks are kept in the resulting strings.

Returns:

A List of Strings containing the input split by line boundaries.

`replace`

replace(self: Self, old: Self, new: Self) -> Self

Return a copy of the string with all occurrences of substring old if replaced by new.

Args:

old (Self): The substring to replace.
new (Self): The substring to replace with.

Returns:

The string where all occurrences of old are replaced with new.

`strip`

strip(self: Self, chars: Self) -> Self

Return a copy of the string with leading and trailing characters removed.

Args:

chars (Self): A set of characters to be removed. Defaults to whitespace.

Returns:

A copy of the string with no leading or trailing characters.

strip(self: Self) -> Self

Return a copy of the string with leading and trailing whitespaces removed.

Returns:

A copy of the string with no leading or trailing whitespaces.

`rstrip`

rstrip(self: Self, chars: Self) -> Self

Return a copy of the string with trailing characters removed.

Args:

chars (Self): A set of characters to be removed. Defaults to whitespace.

Returns:

A copy of the string with no trailing characters.

rstrip(self: Self) -> Self

Return a copy of the string with trailing whitespaces removed.

Returns:

A copy of the string with no trailing whitespaces.

`lstrip`

lstrip(self: Self, chars: Self) -> Self

Return a copy of the string with leading characters removed.

Args:

chars (Self): A set of characters to be removed. Defaults to whitespace.

Returns:

A copy of the string with no leading characters.

lstrip(self: Self) -> Self

Return a copy of the string with leading whitespaces removed.

Returns:

A copy of the string with no leading whitespaces.

`lower`

lower(self: Self) -> Self

Returns a copy of the string with all ASCII cased characters converted to lowercase.

Returns:

A new string where cased letters have been converted to lowercase.

`upper`

upper(self: Self) -> Self

Returns a copy of the string with all ASCII cased characters converted to uppercase.

Returns:

A new string where cased letters have been converted to uppercase.

`startswith`

startswith(self: Self, prefix: Self, start: Int = 0, end: Int = -1) -> Bool

Checks if the string starts with the specified prefix between start and end positions. Returns True if found and False otherwise.

Args:

prefix (Self): The prefix to check.
start (Int): The start offset from which to check.
end (Int): The end offset from which to check.

Returns:

True if the self[start:end] is prefixed by the input prefix.

`endswith`

endswith(self: Self, suffix: Self, start: Int = 0, end: Int = -1) -> Bool

Checks if the string end with the specified suffix between start and end positions. Returns True if found and False otherwise.

Args:

suffix (Self): The suffix to check.
start (Int): The start offset from which to check.
end (Int): The end offset from which to check.

Returns:

True if the self[start:end] is suffixed by the input suffix.

`removeprefix`

removeprefix(self: Self, prefix: Self, /) -> Self

Returns a new string with the prefix removed if it was present.

For example:

print(String('TestHook').removeprefix('Test'))
# 'Hook'
print(String('BaseTestCase').removeprefix('Test'))
# 'BaseTestCase'

Args:

prefix (Self): The prefix to remove from the string.

Returns:

string[len(prefix):] if the string starts with the prefix string, or a copy of the original string otherwise.

`removesuffix`

removesuffix(self: Self, suffix: Self, /) -> Self

Returns a new string with the suffix removed if it was present.

For example:

print(String('TestHook').removesuffix('Hook'))
# 'Test'
print(String('BaseTestCase').removesuffix('Test'))
# 'BaseTestCase'

Args:

suffix (Self): The suffix to remove from the string.

Returns:

string[:-len(suffix)] if the string ends with the suffix string, or a copy of the original string otherwise.

Aliases​

Implemented traits​

Methods​

__init__​

__copyinit__​

__moveinit__​

__bool__​

__getitem__​

__lt__​

__le__​

__eq__​

__ne__​

__gt__​

__ge__​

__contains__​

__add__​

__mul__​

__radd__​

__iadd__​

format_sequence​

format_to​

join​

unsafe_ptr​

unsafe_uint8_ptr​

as_bytes​

as_bytes_slice​

as_string_slice​

count​

find​

rfind​

isspace​

split​

splitlines​

replace​

strip​

rstrip​

lstrip​

lower​

upper​

startswith​

endswith​

removeprefix​

removesuffix​

Aliases

Implemented traits

Methods

`init`

`copyinit`

`moveinit`

`bool`

`getitem`

`lt`

`le`

`eq`

`ne`

`gt`

`ge`

`contains`

`add`

`mul`

`radd`

`iadd`

`format_sequence`

`format_to`

`join`

`unsafe_ptr`

`unsafe_uint8_ptr`

`as_bytes`

`as_bytes_slice`

`as_string_slice`

`count`

`find`

`rfind`

`isspace`

`split`

`splitlines`

`replace`

`strip`

`rstrip`

`lstrip`

`lower`

`upper`

`startswith`

`endswith`

`removeprefix`

`removesuffix`