Skip to main content

Mojo 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, CollectionElementNew, Comparable, Copyable, EqualityComparable, ExplicitlyCopyable, Formattable, Hashable, IntableRaising, KeyElement, Movable, Representable, Sized, Stringable, ToFormatter

Methods

__init__

__init__(inout self: 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__(inout self: Self)

Construct an uninitialized string.

__init__(inout self: Self, *, other: Self)

Explicitly copy the provided value.

Args:

  • other (Self): The value to copy.

__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, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1], 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, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1]): The pointer to the buffer.
  • len (Int): The length of the buffer, including the null terminator.

__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__[IndexerType: Indexer](self: 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: 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.

Examples:

Construct a String from several Formattable arguments:

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

.

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.

__iter__

__iter__(ref [self_is_lifetime] self: Self) -> _StringSliceIter[$0, $1, 1]

Iterate over elements of the string, returning immutable references.

Returns:

An iterator of references to the string elements.

__reversed__

__reversed__(ref [self_is_lifetime] self: Self) -> _StringSliceIter[$0, $1, 0]

Iterate backwards over the string, returning immutable references.

Returns:

A reversed iterator of references to the string elements.

__len__

__len__(self: 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) -> 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) -> Self

Return a Mojo-compatible representation of the String instance.

Returns:

A new representation of the string.

__fspath__

__fspath__(self: Self) -> Self

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

Returns:

The file system path representation as a string.

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.

join[T: StringableCollectionElement](self: 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.

unsafe_ptr

unsafe_ptr(self: Self) -> UnsafePointer[SIMD[uint8, 1], 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1]

Retrieves a pointer to the underlying memory.

Returns:

The pointer to the underlying memory.

unsafe_cstr_ptr

unsafe_cstr_ptr(self: Self) -> UnsafePointer[SIMD[int8, 1], 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 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(self: Self) -> List[SIMD[uint8, 1], 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(ref [self_is_lifetime] self: Self) -> Span[$0, 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_is_lifetime] self: Self) -> 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.

byte_length

byte_length(self: 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: 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 every character in the given String is a python whitespace String. This corresponds to Python's universal separators " \t\n\r\f\v\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: Self, sep: Self, maxsplit: Int = -1) -> List[String, 0]

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.

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

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\r\f\v\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\r\f\v\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: Self, keepends: Bool = 0) -> List[String, 0]

Split the string at line boundaries. This corresponds to Python's universal newlines "\t\n\r\r\n\f\v\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: 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.

__hash__

__hash__(self: 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.

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'
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'
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: Self) -> Int

Parses the given string as a base-10 integer and returns that value.

For example, int("19") returns 19. If the given string cannot be parsed as an integer value, an error is raised. For example, int("hi") raises an error.

Returns:

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

format

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

Format a template with *args.

Example of manual indexing:

print(
String("{0} {1} {0}").format(
"Mojo", 1.125
)
) #Mojo 1.125 Mojo
print(
String("{0} {1} {0}").format(
"Mojo", 1.125
)
) #Mojo 1.125 Mojo

Example of automatic indexing:

var x = String("{} {}").format(
True, "hello world"
)
print(x) #True hello world
var x = String("{} {}").format(
True, "hello world"
)
print(x) #True hello world

Parameters:

  • *Ts (StringRepresentable): The types of the substitution values. Are required to implement Stringable.

Args:

  • *args (*Ts): The substitution values.

Returns:

The template with the given values substituted.

isdigit

isdigit(self: Self) -> Bool

Returns True if all characters in the string are digits.

Note that this currently only works with ASCII strings.

Returns:

True if all characters are digits else False.

isupper

isupper(self: Self) -> Bool

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

Note that this currently only works with ASCII strings.

Returns:

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

islower

islower(self: Self) -> Bool

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

Note that this currently only works with ASCII strings.

Returns:

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

isprintable

isprintable(self: 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: 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: 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: 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.