struct
String
Represents a mutable string.
Implemented traits
AnyType
,
Boolable
,
CollectionElement
,
Copyable
,
EqualityComparable
,
Formattable
,
Hashable
,
IntableRaising
,
KeyElement
,
Movable
,
Sized
,
Stringable
,
ToFormatter
Methods
__init__
__init__(inout self: Self, /, owned impl: List[SIMD[int8, 1]])
Construct a string from a buffer of bytes.
The buffer must be terminated with a null byte:
var buf = List[Int8]()
buf.append(ord('H'))
buf.append(ord('i'))
buf.append(0)
var hi = String(buf)
Args:
- impl (
List[SIMD[int8, 1]]
): The buffer.
__init__(inout self: Self, /)
Construct an uninitialized string.
__init__(inout self: Self, /, str: StringRef)
Construct a string from a StringRef object.
Args:
- str (
StringRef
): The StringRef from which to construct this string object.
__init__(inout self: Self, /, str: StringLiteral)
Constructs a String value given a constant string.
Args:
- str (
StringLiteral
): The input constant string.
__init__[stringable: Stringable](inout self: Self, /, value: stringable)
Creates a string from a value that conforms to Stringable trait.
Parameters:
- stringable (
Stringable
): The Stringable type.
Args:
- value (
stringable
): The value that conforms to Stringable.
__init__(inout self: Self, /, ptr: UnsafePointer[SIMD[int8, 1], 0], len: Int)
Creates a string from the buffer. Note that the string now owns the buffer.
The buffer must be terminated with a null byte.
Args:
- ptr (
UnsafePointer[SIMD[int8, 1], 0]
): The pointer to the buffer. - len (
Int
): The length of the buffer, including the null terminator.
__init__(inout self: Self, /, ptr: LegacyPointer[SIMD[int8, 1], 0], len: Int)
Creates a string from the buffer. Note that the string now owns the buffer.
The buffer must be terminated with a null byte.
Args:
- ptr (
LegacyPointer[SIMD[int8, 1], 0]
): The pointer to the buffer. - len (
Int
): The length of the buffer, including the null terminator.
__init__(inout self: Self, /, ptr: DTypePointer[int8, 0], len: Int)
Creates a string from the buffer. Note that the string now owns the buffer.
The buffer must be terminated with a null byte.
Args:
- ptr (
DTypePointer[int8, 0]
): 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__(self: Self, idx: Int) -> Self
Gets the character at the specified position.
Args:
- idx (
Int
): The index value.
Returns:
A new string containing the character at the specified position.
__getitem__(self: Self, span: Slice) -> Self
Gets the sequence of characters at the specified positions.
Args:
- span (
Slice
): A slice that specifies positions of the new substring.
Returns:
A new string containing the string at the specified positions.
__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.
__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 concantenated 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.
__str__
__str__(self: Self) -> Self
__len__
__len__(self: Self) -> Int
Returns the string length.
Returns:
The string length.
format_sequence
static format_sequence[*Ts: Formattable](*args: *Ts) -> Self
Construct a string by concatenating a sequence of formattable arguments.
Parameters:
- *Ts (
Formattable
): The types of the arguments to format. Each type must be satisfyFormattable
.
Args:
- *args (
*Ts
): A sequence of formattable arguments.
Returns:
A string formed by formatting the argument sequence.
format_to
format_to(self: Self, inout writer: Formatter)
Formats this string to the provided formatter.
Args:
- writer (
Formatter
): The formatter to write to.
join
join[rank: Int](self: Self, elems: StaticIntTuple[rank]) -> Self
Joins the elements from the tuple using the current string as a delimiter.
Parameters:
- rank (
Int
): The size of the tuple.
Args:
- elems (
StaticIntTuple[rank]
): 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.
as_bytes
as_bytes(self: Self) -> List[SIMD[int8, 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.
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.
split
split(self: Self, delimiter: Self) -> List[String]
Split the string by a delimiter.
Args:
- delimiter (
Self
): The string to split on.
Returns:
A List of Strings containing the input split by the delimiter.
Raises:
Error if an empty delimiter is specified.
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 occurences of old
are replaced with new
.
strip
strip(self: Self) -> Self
Return a copy of the string with leading and trailing whitespace characters removed.
See isspace
for a list of whitespace characters
Returns:
A copy of the string with no leading or trailing whitespace characters.
rstrip
rstrip(self: Self) -> Self
Return a copy of the string with trailing whitespace characters removed.
See isspace
for a list of whitespace characters
Returns:
A copy of the string with no trailing whitespace characters.
lstrip
lstrip(self: Self) -> Self
Return a copy of the string with leading whitespace characters removed.
See isspace
for a list of whitespace characters
Returns:
A copy of the string with no leading whitespace characters.
__hash__
__hash__(self: Self) -> Int
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 convered 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
If the string starts with the prefix string, return string[len(prefix):]
. Otherwise, return a copy of the original string.
print(String('TestHook').removeprefix('Test'))
# 'Hook'
print(String('BaseTestCase').removeprefix('Test'))
# 'BaseTestCase'
Args:
- prefix (
Self
): The prefix to remove from the string.
Returns:
A new string with the prefix removed if it was present.
removesuffix
removesuffix(self: Self, suffix: Self, /) -> Self
If the string ends with the suffix string, return string[:-len(suffix)]
. Otherwise, return a copy of the original string.
print(String('TestHook').removesuffix('Hook'))
# 'Test'
print(String('BaseTestCase').removesuffix('Test'))
# 'BaseTestCase'
Args:
- suffix (
Self
): The suffix to remove from the string.
Returns:
A new string with the suffix removed if it was present.
__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.