Version: Nightly

StringLiteral

struct StringLiteral[value: __mlir_type.`!kgen.string`]

This type represents a string literal.

String literals are all null-terminated for compatibility with C APIs, but this is subject to change. String literals store their length as an integer, and this does not include the null terminator.

Parameters

value (__mlir_type.`!kgen.string`): The underlying string value.

Implemented traits

AnyType, Boolable, ConvertibleToPython, Copyable, Defaultable, FloatableRaising, ImplicitlyCopyable, ImplicitlyDestructible, IntableRaising, Movable, PathLike, RegisterPassable, TrivialRegisterPassable, Writable

Methods

`init`

__init__() -> Self

Constructor for any value.

`bool`

__bool__(self) -> Bool

Convert the string to a bool value.

Returns:

Bool: True if the string is not empty.

`getitem`

__getitem__[I: Indexer, //](self, idx: I) -> StaticString

Gets the character at the specified position.

Parameters:

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

Args:

idx (I): The index value.

Returns:

StaticString: A StringSlice view containing the character at the specified position.

`lt`

__lt__(self, rhs: StringSlice[rhs.origin]) -> Bool

Compare this value to the RHS using lesser than (LT) comparison.

Args:

rhs (StringSlice): The other value to compare against.

Returns:

Bool: True if this is strictly less than the RHS and False otherwise.

`le`

__le__(self, rhs: StringSlice[rhs.origin]) -> Bool

Compare this value to the RHS using lesser than or equal to (LE) comparison.

Args:

rhs (StringSlice): The other value to compare against.

Returns:

Bool: True if this is less than or equal to the RHS and False otherwise.

`eq`

__eq__(self, rhs: StringSlice[rhs.origin]) -> Bool

Compare two string literals for equality.

Args:

rhs (StringSlice): The string to compare.

Returns:

Bool: True if they are equal.

`ne`

__ne__(self, rhs: StringSlice[rhs.origin]) -> Bool

Compare two string literals for inequality.

Args:

rhs (StringSlice): The string to compare.

Returns:

Bool: True if they are not equal.

`gt`

__gt__(self, rhs: StringSlice[rhs.origin]) -> Bool

Compare this value to the RHS using greater than (GT) comparison.

Args:

rhs (StringSlice): The other value to compare against.

Returns:

Bool: True if this is strictly greater than the RHS and False otherwise.

`ge`

__ge__(self, rhs: StringSlice[rhs.origin]) -> Bool

Compare this value to the RHS using greater than or equal to (GE) comparison.

Args:

rhs (StringSlice): The other value to compare against.

Returns:

Bool: True if this is greater than or equal to the RHS and False otherwise.

`add`

__add__(self, rhs: StringLiteral[rhs.value]) -> StringLiteral[#pop.string_concat<value, *"rhs.value`2x">]

Concatenate two string literals.

Args:

rhs (StringLiteral): The string to concat.

Returns:

StringLiteral: The concatenated string.

`mul`

__mul__(self, n: Int) -> String

Concatenates the string n times.

Args:

n (Int): The number of times to concatenate the string.

Returns:

String: The string concatenated n times.

`to_python_object`

to_python_object(var self) -> PythonObject

Convert this value to a PythonObject.

Returns:

PythonObject: A PythonObject representing the value.

Raises:

If the Python runtime is not initialized or conversion fails.

`int`

__int__(self) -> Int

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

Returns:

Int: An integer value that represents the string.

Raises:

If the string cannot be parsed as a valid base-10 integer.

`float`

__float__(self) -> Float64

Parses the string as a floating-point number and returns that value.

Returns:

Float64: A float value that represents the string.

Raises:

If the string cannot be parsed as a valid floating-point number.

`fspath`

__fspath__(self) -> String

Return the file system path representation of the object.

Returns:

String: The file system path representation as a string.

`iter`

__iter__(self) -> CodepointSliceIter[StaticConstantOrigin]

Return an iterator over the string literal.

Returns:

CodepointSliceIter: An iterator over the string.

`reversed`

__reversed__(self) -> CodepointSliceIter[StaticConstantOrigin, False]

Iterate backwards over the string, returning immutable references.

Returns:

CodepointSliceIter: A reversed iterator over the string.

`__merge_with__`

__merge_with__[other_type: AnyStruct[StringLiteral[other_type.value]]](self) -> StaticString

Returns a StaticString after merging with another string literal.

Parameters:

other_type (AnyStruct): The type of the string literal to merge with.

Returns:

StaticString: A StaticString after merging with the specified other_type.

`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:

Int: The length of this string in bytes.

`count_codepoints`

count_codepoints(self) -> Int

Calculates the length in Unicode codepoints encoded in the UTF-8 representation of this string.

This is an O(n) operation, where n is the length of the string, as it requires scanning the full string contents.

Examples:

Query the length of a string, in bytes and Unicode codepoints:

var s = StringSlice("ನಮಸ್ಕಾರ")
assert_equal(s.count_codepoints(), 7)
assert_equal(s.byte_length(), 21)

Strings containing only ASCII characters have the same byte and Unicode codepoint length:

var s = StringSlice("abc")
assert_equal(s.count_codepoints(), 3)
assert_equal(s.byte_length(), 3)

The character length of a string with visual combining characters is the length in Unicode codepoints, not grapheme clusters:

var s = StringSlice("á")
assert_equal(s.count_codepoints(), 2)
assert_equal(s.byte_length(), 3)

Notes: This method needs to traverse the whole string to count, so it has a performance hit compared to using the byte length.

Returns:

Int: The length in Unicode codepoints.

`unsafe_ptr`

unsafe_ptr(self) -> UnsafePointer[UInt8, StaticConstantOrigin]

Get raw pointer to the underlying data.

Returns:

UnsafePointer: The raw pointer to the data.

`as_c_string_slice`

as_c_string_slice(self) -> CStringSlice[StaticConstantOrigin]

Return a CStringSlice to the underlying memory of the string.

Returns:

CStringSlice: The CStringSlice of the string.

`as_string_slice`

as_string_slice(self) -> StaticString

Returns a string slice of this static string literal.

Returns:

StaticString: A string slice pointing to this static string literal.

`as_bytes`

as_bytes(self) -> Span[UInt8, StaticConstantOrigin]

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

Returns:

Span: A contiguous slice pointing to the bytes owned by this string.

`write_to`

write_to(self, mut writer: T)

Formats this string literal to the provided Writer.

Args:

writer (T): The object to write to.

`write_repr_to`

write_repr_to(self, mut writer: T)

Write the string representation of the string literal.

Args:

writer (T): The value to write to.

`find`

find(self, substr: StringSlice[StaticConstantOrigin], start: Int = 0) -> Int

Finds the offset of the first occurrence of substr starting at start. If not found, returns -1.

Args:

substr (StringSlice): The substring to find.
start (Int): The offset from which to find.

Returns:

Int: The offset of substr relative to the beginning of the string.

`rfind`

rfind(self, substr: StringSlice[StaticConstantOrigin], start: Int = 0) -> Int

Finds the offset of the last occurrence of substr starting at start. If not found, returns -1.

Args:

substr (StringSlice): The substring to find.
start (Int): The offset from which to find.

Returns:

Int: The offset of substr relative to the beginning of the string.

`count`

count(self, substr: StringSlice[substr.origin]) -> Int

Return the number of non-overlapping occurrences of substring substr in the string literal.

If sub is empty, returns the number of empty strings between characters which is the length of the string plus one.

Args:

substr (StringSlice): The substring to count.

Returns:

Int: The number of occurrences of substr.

`lower`

lower(self) -> String

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

Returns:

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

`upper`

upper(self) -> String

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

Returns:

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

`ascii_rjust`

ascii_rjust(self, width: Int, fillchar: StringSlice[StaticConstantOrigin] = StringSlice(" ")) -> String

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

Pads the string literal on the left with the specified fill character so that the total byte length of the resulting string equals width. If the original string literal is already longer than or equal to width, returns the string literal unchanged (as a String).

Examples:

var s = "hello"
print(s.ascii_rjust(10))        # "     hello"
print(s.ascii_rjust(10, "*"))   # "*****hello"
print(s.ascii_rjust(3))         # "hello" (no padding)

Args:

width (Int): The total width (in bytes) of the resulting string. This is not the amount of padding, but the final length of the returned string.
fillchar (StringSlice): The padding character to use (defaults to space). Must be a single-byte character.

Returns:

String: A right-justified string of byte length width, or the original string literal (as a String) if its length is already greater than or equal to width.

`ascii_ljust`

ascii_ljust(self, width: Int, fillchar: StringSlice[StaticConstantOrigin] = StringSlice(" ")) -> String

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

Pads the string literal on the right with the specified fill character so that the total byte length of the resulting string equals width. If the original string literal is already longer than or equal to width, returns the string literal unchanged (as a String).

Examples:

var s = "hello"
print(s.ascii_ljust(10))        # "hello     "
print(s.ascii_ljust(10, "*"))   # "hello*****"
print(s.ascii_ljust(3))         # "hello" (no padding)

Args:

width (Int): The total width (in bytes) of the resulting string. This is not the amount of padding, but the final length of the returned string.
fillchar (StringSlice): The padding character to use (defaults to space). Must be a single-byte character.

Returns:

String: A left-justified string of (byte) length width, or the original string literal (as a String) if its length is already greater than or equal to width.

`ascii_center`

ascii_center(self, width: Int, fillchar: StringSlice[StaticConstantOrigin] = StringSlice(" ")) -> String

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

Pads the string literal on both sides with the specified fill character so that the total length of the resulting string equals width. If the padding needed is odd, the extra character goes on the right side. If the original string literal is already longer than or equal to width, returns the string literal unchanged (as a String).

Examples:

var s = "hello"
print(s.ascii_center(10))        # "  hello   "
print(s.ascii_center(11, "*"))   # "***hello***"
print(s.ascii_center(3))         # "hello" (no padding)

Args:

width (Int): The total width (in bytes) of the resulting string. This is not the amount of padding, but the final length of the returned string.
fillchar (StringSlice): The padding character to use (defaults to space). Must be a single-byte character.

Returns:

String: A center-justified string of length width, or the original string literal (as a String) if its length is already greater than or equal to width.

`startswith`

startswith(self, prefix: StringSlice[prefix.origin], start: Int = 0, end: Int = -1) -> Bool

Checks if the string literal starts with the specified prefix between start and end positions. Returns True if found and False otherwise.

Args:

prefix (StringSlice): The prefix to check.
start (Int): The start byte offset from which to check.
end (Int): The end byte offset from which to check.

Returns:

Bool: True if the self[byte=start:end] is prefixed by the input prefix.

`endswith`

endswith(self, suffix: StringSlice[suffix.origin], start: Int = 0, end: Int = -1) -> Bool

Checks if the string literal end with the specified suffix between start and end positions. Returns True if found and False otherwise.

Args:

suffix (StringSlice): The suffix to check.
start (Int): The start byte offset from which to check.
end (Int): The end byte offset from which to check.

Returns:

Bool: True if the self[byte=start:end] is suffixed by the input suffix.

`is_ascii_digit`

is_ascii_digit(self) -> Bool

Returns True if all characters in the string literal are ASCII digits.

Note that this currently only works with ASCII strings.

Returns:

Bool: True if all characters are digits else False.

`isupper`

isupper(self) -> Bool

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

Note that this currently only works with ASCII strings.

Returns:

Bool: True if all cased characters in the string literal 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 literal are lowercase and there is at least one cased character.

Note that this currently only works with ASCII strings.

Returns:

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

`strip`

strip(self) -> StaticString

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

Returns:

StaticString: A string with no leading or trailing whitespaces.

strip(self, chars: StringSlice[chars.origin]) -> StaticString

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

Args:

chars (StringSlice): A set of characters to be removed. Defaults to whitespace.

Returns:

StaticString: A string with no leading or trailing characters.

`rstrip`

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

Return a copy of the string literal with trailing characters removed.

Args:

chars (StringSlice): A set of characters to be removed. Defaults to whitespace.

Returns:

StaticString: A string with no trailing characters.

rstrip(self) -> StaticString

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:

StaticString: A copy of the string with no trailing whitespaces.

`lstrip`

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

Return a copy of the string with leading characters removed.

Args:

chars (StringSlice): A set of characters to be removed. Defaults to whitespace.

Returns:

StaticString: A copy of the string with no leading characters.

lstrip(self) -> StaticString

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:

StaticString: A copy of the string with no leading whitespaces.

`codepoint_slices`

codepoint_slices(self) -> CodepointSliceIter[StaticConstantOrigin]

Iterate over the string's codepoints as immutable slices.

Returns:

CodepointSliceIter: An iterator of codepoint slices.

`codepoint_slices_reversed`

codepoint_slices_reversed(self) -> CodepointSliceIter[StaticConstantOrigin, False]

Iterates backwards over the string literal, returning single-character slices.

Each returned slice points to a single Unicode codepoint encoded in the underlying UTF-8 representation of this string literal, starting from the end and moving towards the beginning.

Returns:

CodepointSliceIter: A reversed iterator of references to the string literal elements.

`codepoints`

codepoints(self) -> CodepointsIter[StaticConstantOrigin]

Iterate over the Codepoints in this string constant.

Returns:

CodepointsIter: An iterator over successive Codepoint values.

`format`

format[*Ts: Writable](self, *args: *Ts.values) -> String

Produce a formatted string using the current string as a template.

The template, or "format string" can contain literal text and/or replacement fields delimited with curly braces ({}). Returns a copy of the format string with the replacement fields replaced with string representations of the args arguments.

For more information, see the discussion in the format module.

Example:

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

Parameters:

*Ts (Writable): The types of substitution values that implement Writable.

Args:

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

Returns:

String: The template with the given values substituted.

`join`

join[T: Copyable & Writable, //](self, elems: Span[T, elems.origin]) -> String

Joins string elements using the current string as a delimiter. Defaults to writing to the stack if total bytes of elems is less than buffer_size, otherwise will allocate once to the heap and write directly into that. The buffer_size defaults to 4096 bytes to match the default page size on arm64 and x86-64.

Parameters:

T (Copyable & Writable): The type of the elements. Must implement the Copyable, and Writable traits.

Args:

elems (Span): The input values.

Returns:

String: The joined string.

`split`

split(self, sep: StringSlice[sep.origin]) -> List[StringSlice[StaticConstantOrigin]]

Split the string by a separator.

Examples:

# Splitting a space
_ = StringSlice("hello world").split(" ") # ["hello", "world"]
# Splitting adjacent separators
_ = StringSlice("hello,,world").split(",") # ["hello", "", "world"]
# Splitting with starting or ending separators
_ = StringSlice(",1,2,3,").split(",") # ['', '1', '2', '3', '']
# Splitting with an empty separator
_ = StringSlice("123").split("") # ['', '1', '2', '3', '']

Args:

sep (StringSlice): The string to split on.

Returns:

List: A List of Strings containing the input split by the separator.

split(self, sep: StringSlice[sep.origin], maxsplit: Int) -> List[StringSlice[StaticConstantOrigin]]

Split the string by a separator.

Examples:

# Splitting with maxsplit
_ = StringSlice("1,2,3").split(",", maxsplit=1) # ['1', '2,3']
# Splitting with starting or ending separators
_ = StringSlice(",1,2,3,").split(",", maxsplit=1) # ['', '1,2,3,']
# Splitting with an empty separator
_ = StringSlice("123").split("", maxsplit=1) # ['', '123']

Args:

sep (StringSlice): The string to split on.
maxsplit (Int): The maximum amount of items to split from String.

Returns:

List: A List of Strings containing the input split by the separator.

split(self, sep: NoneType = None) -> List[StringSlice[StaticConstantOrigin]]

Split the string by every Whitespace separator.

Examples:

# Splitting an empty string or filled with whitespaces
_ = StringSlice("      ").split() # []
_ = StringSlice("").split() # []

# Splitting a string with leading, trailing, and middle whitespaces
_ = StringSlice("      hello    world     ").split() # ["hello", "world"]
# Splitting adjacent universal newlines:
_ = StringSlice(
    "hello \t\n\v\f\r\x1c\x1d\x1e\x85world"
).split()  # ["hello", "world"]

Args:

sep (NoneType): None.

Returns:

List: A List of Strings containing the input split by the separator.

split(self, sep: NoneType = None, *, maxsplit: Int) -> List[StringSlice[StaticConstantOrigin]]

Split the string by every Whitespace separator.

Examples:

# Splitting with maxsplit
_ = StringSlice("1     2  3").split(maxsplit=1) # ['1', '2  3']

Args:

sep (NoneType): None.
maxsplit (Int): The maximum amount of items to split from String.

Returns:

List: A List of Strings containing the input split by the separator.

Parameters​

Implemented traits​

Methods​

__init__​

__bool__​

__getitem__​

__lt__​

__le__​

__eq__​

__ne__​

__gt__​

__ge__​

__add__​

__mul__​

to_python_object​

__int__​

__float__​

__fspath__​

__iter__​

__reversed__​

__merge_with__​

byte_length​

count_codepoints​

unsafe_ptr​

as_c_string_slice​

as_string_slice​

as_bytes​

write_to​

write_repr_to​

find​

rfind​

count​

lower​

upper​

ascii_rjust​

ascii_ljust​

ascii_center​

startswith​

endswith​

is_ascii_digit​

isupper​

islower​

strip​

rstrip​

lstrip​

codepoint_slices​

codepoint_slices_reversed​

codepoints​

format​

join​

split​

Parameters

Implemented traits

Methods

`init`

`bool`

`getitem`

`lt`

`le`

`eq`

`ne`

`gt`

`ge`

`add`

`mul`

`to_python_object`

`int`

`float`

`fspath`

`iter`

`reversed`

`__merge_with__`

`byte_length`

`count_codepoints`

`unsafe_ptr`

`as_c_string_slice`

`as_string_slice`

`as_bytes`

`write_to`

`write_repr_to`

`find`

`rfind`

`count`

`lower`

`upper`

`ascii_rjust`

`ascii_ljust`

`ascii_center`

`startswith`

`endswith`

`is_ascii_digit`

`isupper`

`islower`

`strip`

`rstrip`

`lstrip`

`codepoint_slices`

`codepoint_slices_reversed`

`codepoints`

`format`

`join`

`split`