Skip to main content
Log in

Mojo struct

String

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, UnknownDestructibility, Writable, Writer, _HashableWithHasher

Methods

__init__

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

Construct a string from a buffer of bytes without copying the allocated data.

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.

@implicit __init__(out self, impl: List[SIMD[uint8, 1], True])

Construct a string from a buffer of bytes, copying the allocated data. Use the transfer operator ^ to avoid the copy.

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], True]): 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.

@implicit __init__(out self, str: StringRef)

Construct a string from a StringRef object.

Args:

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

@implicit __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.

@implicit __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__(mut self, other: Self)

Appends another string to this string.

Args:

  • other (Self): The string to append.

__iadd__(mut self, other: StringLiteral)

Appends another string literal to this string.

Args:

  • other (StringLiteral): The string to append.

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

Appends another string slice to this string.

Args:

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

write_bytes

write_bytes(mut 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](mut 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[self]

Iterate over the string, returning immutable references.

Returns:

An iterator of references to the string elements.

__reversed__

__reversed__(self) -> _StringSliceIter[self, False]

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, mut 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(ref self) -> UnsafePointer[SIMD[uint8, 1], mut=self_is_mut, origin=self_is_origin]

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

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[self_is_origin]

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 = 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 = False) -> 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: StringSlice[origin]) -> StringSlice[self]

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

Args:

  • chars (StringSlice[origin]): A set of characters to be removed. Defaults to whitespace.

Returns:

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

strip(self) -> StringSlice[self]

Return a copy of the string with leading and trailing whitespaces removed. This only takes ASCII whitespace into account: " \t\n\v\f\r\x1c\x1d\x1e".

Returns:

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

rstrip

rstrip(self, chars: StringSlice[origin]) -> StringSlice[self]

Return a copy of the string with trailing characters removed.

Args:

  • chars (StringSlice[origin]): A set of characters to be removed. Defaults to whitespace.

Returns:

A copy of the string with no trailing characters.

rstrip(self) -> StringSlice[self]

Return a copy of the string with trailing whitespaces removed. This only takes ASCII whitespace into account: " \t\n\v\f\r\x1c\x1d\x1e".

Returns:

A copy of the string with no trailing whitespaces.

lstrip

lstrip(self, chars: StringSlice[origin]) -> StringSlice[self]

Return a copy of the string with leading characters removed.

Args:

  • chars (StringSlice[origin]): A set of characters to be removed. Defaults to whitespace.

Returns:

A copy of the string with no leading characters.

lstrip(self) -> StringSlice[self]

Return a copy of the string with leading whitespaces removed. This only takes ASCII whitespace into account: " \t\n\v\f\r\x1c\x1d\x1e".

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