Nightly Build: This page might be unfinished.See the released version.

Mojo struct

String

Represents a mutable string.

Aliases

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

Implemented traits

AnyType, AsBytes, Boolable, BytesCollectionElement, CollectionElement, CollectionElementNew, Comparable, Copyable, EqualityComparable, ExplicitlyCopyable, FloatableRaising, Hashable, IntableRaising, KeyElement, Movable, Representable, Sized, Stringable, Stringlike, Writable, Writer, _HashableWithHasher

Methods

`init`

__init__(out self, owned impl: List[SIMD[uint8, 1], hint_trivial_type])

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)
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], hint_trivial_type]): The buffer.

__init__(out self)

Construct an uninitialized string.

__init__(out self, *, capacity: Int)

Construct an uninitialized string with the given capacity.

Args:

capacity (Int): The capacity of the string.

__init__(out self, *, other: Self)

Explicitly copy the provided value.

Args:

other (Self): The value to copy.

__init__(out self, str: StringRef)

Construct a string from a StringRef object.

Args:

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

__init__(out self, str_slice: StringSlice[origin])

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[origin]): The string slice from which to construct this string.

__init__(out self, literal: StringLiteral)

Constructs a String value given a constant string.

Args:

literal (StringLiteral): The input constant string.

__init__(out self, *, ptr: UnsafePointer[SIMD[uint8, 1]], length: 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]]): The pointer to the buffer.
length (Int): The length of the buffer, including the null terminator.

`bool`

__bool__(self) -> Bool

Checks if the string is not empty.

Returns:

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

`getitem`

__getitem__[IndexerType: Indexer](self, idx: IndexerType) -> Self

Gets the character at the specified position.

Parameters:

IndexerType (Indexer): The inferred type of an indexer argument.

Args:

idx (IndexerType): The index value.

Returns:

A new string containing the character at the specified position.

__getitem__(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, 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, 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, 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, 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, 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, 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, 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, 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.

__add__(self, other: StringLiteral) -> Self

Creates a string by appending a string literal at the end.

Args:

other (StringLiteral): The string literal to append.

Returns:

The new constructed string.

__add__(self, other: StringSlice[origin]) -> Self

Creates a string by appending a string slice at the end.

Args:

other (StringSlice[origin]): The string slice to append.

Returns:

The new constructed string.

`mul`

__mul__(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, 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.

__radd__(self, other: StringLiteral) -> Self

Creates a string by prepending another string literal to the start.

Args:

other (StringLiteral): The string to prepend.

Returns:

The new constructed string.

__radd__(self, other: StringSlice[origin]) -> Self

Creates a string by prepending another string slice to the start.

Args:

other (StringSlice[origin]): The string to prepend.

Returns:

The new constructed string.

`iadd`

__iadd__(inout self, other: Self)

Appends another string to this string.

Args:

other (Self): The string to append.

__iadd__(inout self, other: StringLiteral)

Appends another string literal to this string.

Args:

other (StringLiteral): The string to append.

__iadd__(inout self, other: StringSlice[origin])

Appends another string slice to this string.

Args:

other (StringSlice[origin]): The string to append.

`write_bytes`

write_bytes(inout self, bytes: Span[SIMD[uint8, 1], origin])

Write a byte span to this String.

Args:

bytes (Span[SIMD[uint8, 1], origin]): The byte span to write to this String. Must NOT be null terminated.

`write`

write[*Ts: Writable](inout self, *args: *Ts)

Write a sequence of Writable arguments to the provided Writer.

Parameters:

*Ts (Writable): Types of the provided argument sequence.

Args:

*args (*Ts): Sequence of arguments to write to this Writer.

static write[*Ts: Writable](*args: *Ts, *, sep: StringSlice[StaticConstantOrigin] = StringSlice(""), end: StringSlice[StaticConstantOrigin] = StringSlice("")) -> Self

Construct a string by concatenating a sequence of Writable arguments.

Examples:

Construct a String from several Writable arguments:

var string = String.write(1, ", ", 2.0, ", ", "three")
print(string) # "1, 2.0, three"
var string = String.write(1, ", ", 2.0, ", ", "three")
print(string) # "1, 2.0, three"

Parameters:

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

Args:

*args (*Ts): A sequence of Writable arguments.
sep (StringSlice[StaticConstantOrigin]): The separator used between elements.
end (StringSlice[StaticConstantOrigin]): The String to write after printing the elements.

Returns:

A string formed by formatting the argument sequence.

static write[*Ts: Writable](args: VariadicPack[origin, Writable, Ts], sep: StringSlice[StaticConstantOrigin] = StringSlice(""), end: StringSlice[StaticConstantOrigin] = StringSlice("")) -> Self

Construct a string by passing a variadic pack.

Examples:

fn variadic_pack_to_string[
    *Ts: Writable,
](*args: *Ts) -> String:
    return String.write(args)

string = variadic_pack_to_string(1, ", ", 2.0, ", ", "three")
fn variadic_pack_to_string[
    *Ts: Writable,
](*args: *Ts) -> String:
    return String.write(args)

string = variadic_pack_to_string(1, ", ", 2.0, ", ", "three")

Parameters:

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

Args:

args (VariadicPack[origin, Writable, Ts]): A VariadicPack of Writable arguments.
sep (StringSlice[StaticConstantOrigin]): The separator used between elements.
end (StringSlice[StaticConstantOrigin]): The String to write after printing the elements.

Returns:

A string formed by formatting the VariadicPack.

`iter`

__iter__(self) -> _StringSliceIter[*[0,0]]

Iterate over the string, returning immutable references.

Returns:

An iterator of references to the string elements.

`reversed`

__reversed__(self) -> _StringSliceIter[*[0,0], 0]

Iterate backwards over the string, returning immutable references.

Returns:

A reversed iterator of references to the string elements.

`len`

__len__(self) -> Int

Gets the string length, in bytes (for now) PREFER: String.byte_length(), a future version will make this method return Unicode codepoints.

Returns:

The string length, in bytes (for now).

`str`

__str__(self) -> Self

Gets the string itself.

This method ensures that you can pass a String to a method that takes a Stringable value.

Returns:

The string itself.

`repr`

__repr__(self) -> Self

Return a Mojo-compatible representation of the String instance.

Returns:

A new representation of the string.

`fspath`

__fspath__(self) -> Self

Return the file system path representation (just the string itself).

Returns:

The file system path representation as a string.

`write_to`

write_to[W: Writer](self, inout writer: W)

Formats this string to the provided Writer.

Parameters:

W (Writer): A type conforming to the Writable trait.

Args:

writer (W): The object to write to.

`join`

join(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: Writable](self, *elems: *Types) -> Self

Joins string elements using the current string as a delimiter.

Parameters:

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

Args:

*elems (*Types): The input values.

Returns:

The joined string.

join[T: StringableCollectionElement](self, elems: List[T, hint_trivial_type]) -> Self

Joins string elements using the current string as a delimiter.

Parameters:

T (StringableCollectionElement): The types of the elements.

Args:

elems (List[T, hint_trivial_type]): The input values.

Returns:

The joined string.

`fast_join`

fast_join[T: BytesCollectionElement, //](self, elems: List[T, hint_trivial_type]) -> Self

Joins string elements using the current string as a delimiter.

Parameters:

T (BytesCollectionElement): The types of the elements.

Args:

elems (List[T, hint_trivial_type]): The input values.

Returns:

The joined string.

`unsafe_ptr`

unsafe_ptr(self) -> UnsafePointer[SIMD[uint8, 1]]

Retrieves a pointer to the underlying memory.

Returns:

The pointer to the underlying memory.

`unsafe_cstr_ptr`

unsafe_cstr_ptr(self) -> UnsafePointer[SIMD[int8, 1]]

Retrieves a C-string-compatible pointer to the underlying memory.

The returned pointer is guaranteed to be null, or NUL terminated.

Returns:

The pointer to the underlying memory.

`as_bytes`

as_bytes(ref self) -> Span[SIMD[uint8, 1], $1]

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

Notes: 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(ref self) -> StringSlice[$1]

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

Returns:

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

`byte_length`

byte_length(self) -> Int

Get the string length in bytes.

Notes: This does not include the trailing null terminator in the count.

Returns:

The length of this string in bytes, excluding null terminator.

`count`

count(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, 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, 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) -> Bool

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

Returns:

True if the whole String is made up of whitespace characters listed above, otherwise False.

`split`

split(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']
# 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.

Raises:

If the separator is empty.

split(self, sep: NoneType = #kgen.none, maxsplit: Int = -1) -> List[String]

Split the string by every Whitespace separator.

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"]
# Splitting adjacent universal newlines:
_ = String(
    "hello \t\n\v\f\r\x1c\x1d\x1e\x85\u2028\u2029world"
).split()  # ["hello", "world"]
# 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"]
# Splitting adjacent universal newlines:
_ = String(
    "hello \t\n\v\f\r\x1c\x1d\x1e\x85\u2028\u2029world"
).split()  # ["hello", "world"]

Args:

sep (NoneType): None.
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, keepends: Bool = 0) -> List[String]

Split the string at line boundaries. This corresponds to Python's universal newlines: "\r\n" and "\t\n\v\f\r\x1c\x1d\x1e\x85\u2028\u2029".

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, 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, 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

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, 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

Return a copy of the string with trailing whitespaces removed.

Returns:

A copy of the string with no trailing whitespaces.

`lstrip`

lstrip(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

Return a copy of the string with leading whitespaces removed.

Returns:

A copy of the string with no leading whitespaces.

`hash`

__hash__(self) -> UInt

Hash the underlying buffer using builtin hash.

Returns:

A 64-bit hash value. This value is not suitable for cryptographic uses. Its intended usage is for data structures. See the hash builtin documentation for more details.

__hash__[H: _Hasher](self, inout hasher: H)

Updates hasher with the underlying bytes.

Parameters:

H (_Hasher): The hasher type.

Args:

hasher (H): The hasher instance.

`lower`

lower(self) -> Self

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

Returns:

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

`upper`

upper(self) -> Self

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

Returns:

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

`startswith`

startswith(ref 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, 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, 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'
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, 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'
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.

`int`

__int__(self) -> Int

Parses the given string as a base-10 integer and returns that value. If the string cannot be parsed as an int, an error is raised.

Returns:

An integer value that represents the string, or otherwise raises.

`float`

__float__(self) -> SIMD[float64, 1]

Parses the string as a float point number and returns that value. If the string cannot be parsed as a float, an error is raised.

Returns:

A float value that represents the string, or otherwise raises.

`format`

format[*Ts: _CurlyEntryFormattable](self, *args: *Ts) -> Self

Format a template with *args.

Examples:

# Manual indexing:
print(String("{0} {1} {0}").format("Mojo", 1.125)) # Mojo 1.125 Mojo
# Automatic indexing:
print(String("{} {}").format(True, "hello world")) # True hello world
# Manual indexing:
print(String("{0} {1} {0}").format("Mojo", 1.125)) # Mojo 1.125 Mojo
# Automatic indexing:
print(String("{} {}").format(True, "hello world")) # True hello world

Parameters:

*Ts (_CurlyEntryFormattable): The types of substitution values that implement Representable and Stringable (to be changed and made more flexible).

Args:

*args (*Ts): The substitution values.

Returns:

The template with the given values substituted.

`isdigit`

isdigit(self) -> Bool

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

Note that this currently only works with ASCII strings.

Returns:

True if all characters are digits and it's not empty else False.

`isupper`

isupper(self) -> Bool

Returns True if all cased characters in the string are uppercase and there is at least one cased character.

Returns:

True if all cased characters in the string are uppercase and there is at least one cased character, False otherwise.

`islower`

islower(self) -> Bool

Returns True if all cased characters in the string are lowercase and there is at least one cased character.

Returns:

True if all cased characters in the string are lowercase and there is at least one cased character, False otherwise.

`isprintable`

isprintable(self) -> Bool

Returns True if all characters in the string are ASCII printable.

Note that this currently only works with ASCII strings.

Returns:

True if all characters are printable else False.

`rjust`

rjust(self, width: Int, fillchar: StringLiteral = " ") -> Self

Returns the string right justified in a string of specified width.

Args:

width (Int): The width of the field containing the string.
fillchar (StringLiteral): Specifies the padding character.

Returns:

Returns right justified string, or self if width is not bigger than self length.

`ljust`

ljust(self, width: Int, fillchar: StringLiteral = " ") -> Self

Returns the string left justified in a string of specified width.

Args:

width (Int): The width of the field containing the string.
fillchar (StringLiteral): Specifies the padding character.

Returns:

Returns left justified string, or self if width is not bigger than self length.

`center`

center(self, width: Int, fillchar: StringLiteral = " ") -> Self

Returns the string center justified in a string of specified width.

Args:

width (Int): The width of the field containing the string.
fillchar (StringLiteral): Specifies the padding character.

Returns:

Returns center justified string, or self if width is not bigger than self length.

`reserve`

reserve(inout self, new_capacity: Int)

Reserves the requested capacity.

Notes: If the current capacity is greater or equal, this is a no-op. Otherwise, the storage is reallocated and the data is moved.

Args:

new_capacity (Int): The new capacity.

Was this page helpful?

Thank you! We'll create more content like this.

Thank you for helping us improve!

Aliases​

Implemented traits​

Methods​

__init__​

__bool__​

__getitem__​

__lt__​

__le__​

__eq__​

__ne__​

__gt__​

__ge__​

__contains__​

__add__​

__mul__​

__radd__​

__iadd__​

write_bytes​

write​

__iter__​

__reversed__​

__len__​

__str__​

__repr__​

__fspath__​

write_to​

join​

fast_join​

unsafe_ptr​

unsafe_cstr_ptr​

as_bytes​

as_string_slice​

byte_length​

count​

find​

rfind​

isspace​

split​

splitlines​

replace​

strip​

rstrip​

lstrip​

__hash__​

lower​

upper​

startswith​

endswith​

removeprefix​

removesuffix​

__int__​

__float__​

format​

isdigit​

isupper​

islower​

isprintable​

rjust​

ljust​

center​

reserve​

Aliases

Implemented traits

Methods

`init`

`bool`

`getitem`

`lt`

`le`

`eq`

`ne`

`gt`

`ge`

`contains`

`add`

`mul`

`radd`

`iadd`

`write_bytes`

`write`

`iter`

`reversed`

`len`

`str`

`repr`

`fspath`

`write_to`

`join`

`fast_join`

`unsafe_ptr`

`unsafe_cstr_ptr`

`as_bytes`

`as_string_slice`

`byte_length`

`count`

`find`

`rfind`

`isspace`

`split`

`splitlines`

`replace`

`strip`

`rstrip`

`lstrip`

`hash`

`lower`

`upper`

`startswith`

`endswith`

`removeprefix`

`removesuffix`

`int`

`float`

`format`

`isdigit`

`isupper`

`islower`

`isprintable`

`rjust`

`ljust`

`center`

`reserve`