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 satisfyWritable
.
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 satisfyWritable
.
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 implementRepresentable
andStringable
(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.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!