Skip to main content
Log in

Mojo struct

StringLiteral

@register_passable(trivial) struct StringLiteral

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.

Aliases

  • type = string:

Fields

  • value (string): The underlying storage for the string literal.

Implemented traits

AnyType, AsBytes, Boolable, BytesCollectionElement, CollectionElement, CollectionElementNew, Comparable, Copyable, EqualityComparable, EqualityComparableCollectionElement, ExplicitlyCopyable, FloatableRaising, Hashable, IntableRaising, KeyElement, Movable, Representable, Sized, Stringable, UnknownDestructibility, Writable, _CurlyEntryFormattable, _HashableWithHasher

Methods

__init__

__init__(out self, value: string)

Create a string literal from a builtin string type.

Args:

  • value (string): The string value.

__init__(out self, *, other: Self)

Copy constructor.

Args:

  • other (Self): The string literal to copy.

__bool__

__bool__(self) -> Bool

Convert the string to a bool value.

Returns:

True if the string is not empty.

__getitem__

__getitem__[IndexerType: Indexer](self, idx: IndexerType) -> String

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.

__lt__

__lt__(self, rhs: Self) -> Bool

Compare this StringLiteral to the RHS using LT comparison.

Args:

  • rhs (Self): The other StringLiteral to compare against.

Returns:

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

__le__

__le__(self, rhs: Self) -> Bool

Compare this StringLiteral to the RHS using LE comparison.

Args:

  • rhs (Self): The other StringLiteral to compare against.

Returns:

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

__eq__

__eq__(self, rhs: Self) -> Bool

Compare two string literals for equality.

Args:

  • rhs (Self): The string to compare.

Returns:

True if they are equal.

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

Compare two string literals for equality.

Args:

  • rhs (StringSlice[origin]): The string to compare.

Returns:

True if they are equal.

__ne__

__ne__(self, rhs: Self) -> Bool

Compare two string literals for inequality.

Args:

  • rhs (Self): The string to compare.

Returns:

True if they are not equal.

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

Compare two string literals for inequality.

Args:

  • rhs (StringSlice[origin]): The string to compare.

Returns:

True if they are not equal.

__gt__

__gt__(self, rhs: Self) -> Bool

Compare this StringLiteral to the RHS using GT comparison.

Args:

  • rhs (Self): The other StringLiteral to compare against.

Returns:

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

__ge__

__ge__(self, rhs: Self) -> Bool

Compare this StringLiteral to the RHS using GE comparison.

Args:

  • rhs (Self): The other StringLiteral to compare against.

Returns:

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

__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, rhs: Self) -> Self

Concatenate two string literals.

Args:

  • rhs (Self): The string to concat.

Returns:

The concatenated string.

__mul__

__mul__(self, n: IntLiteral) -> Self

Concatenates the string literal n times. Can only be evaluated at compile time using the alias keyword, which will write the result into The binary.

Examples:

alias concat = "mojo" * 3
print(concat) # mojomojomojo
alias concat = "mojo" * 3
print(concat) # mojomojomojo

.

Args:

  • n (IntLiteral): The number of times to concatenate the string literal.

Returns:

The string concatenated n times.

__mul__(self, n: Int) -> String

Concatenates the string n times.

Args:

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

Returns:

The string concatenated n times.

__iadd__

__iadd__(mut self, rhs: Self)

Concatenate a string literal to an existing one. Can only be evaluated at compile time using the alias keyword, which will write the result into the binary.

Example:

fn add_literal(
owned original: StringLiteral, add: StringLiteral, n: Int
) -> StringLiteral:
for _ in range(n):
original += add
return original


fn main():
alias original = "mojo"
alias concat = add_literal(original, "!", 4)
print(concat)
fn add_literal(
owned original: StringLiteral, add: StringLiteral, n: Int
) -> StringLiteral:
for _ in range(n):
original += add
return original


fn main():
alias original = "mojo"
alias concat = add_literal(original, "!", 4)
print(concat)

Result:

mojo!!!!
mojo!!!!

Args:

  • rhs (Self): The string to concat.

get

static get[value: String]() -> Self

Form a string literal from an arbitrary compile-time String value.

Parameters:

  • value (String): The value to convert to StringLiteral.

Returns:

The string value as a StringLiteral.

static get[type: Stringable, //, value: $0]() -> Self

Form a string literal from an arbitrary compile-time stringable value.

Parameters:

  • type (Stringable): The type of the value.
  • value ($0): The value to serialize.

Returns:

The string value as a StringLiteral.

__len__

__len__(self) -> Int

Get the string length.

Returns:

The length of this StringLiteral.

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

__str__

__str__(self) -> String

Convert the string literal to a string.

Returns:

A new string.

__repr__

__repr__(self) -> String

Return a representation of the StringLiteral instance.

You don't need to call this method directly, use repr("...") instead.

Returns:

A new representation of the string.

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

__fspath__

__fspath__(self) -> String

Return the file system path representation of the object.

Returns:

The file system path representation as a string.

__iter__

__iter__(ref self) -> _StringSliceIter[StaticConstantOrigin]

Return an iterator over the string literal.

Returns:

An iterator over the string.

__reversed__

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

Iterate backwards over the string, returning immutable references.

Returns:

A reversed iterator over the 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 StringLiteral in bytes.

unsafe_ptr

unsafe_ptr(self) -> UnsafePointer[SIMD[uint8, 1]]

Get raw pointer to the underlying data.

Returns:

The raw pointer to the data.

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 NUL terminated, and not null.

Returns:

The pointer to the underlying memory.

as_string_slice

as_string_slice(self) -> StringSlice[StaticConstantOrigin]

Returns a string slice of this static string literal.

Returns:

A string slice pointing to this static string literal.

as_bytes

as_bytes(self) -> Span[SIMD[uint8, 1], StaticConstantOrigin]

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

Returns:

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

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.

format

format[*Ts: _CurlyEntryFormattable](self, *args: *Ts) -> String

Format a template with *args.

Examples:

# Manual indexing:
print("{0} {1} {0}".format("Mojo", 1.125)) # Mojo 1.125 Mojo
# Automatic indexing:
print("{} {}".format(True, "hello world")) # True hello world
# 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 (_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.

write_to

write_to[W: Writer](self, mut writer: W)

Formats this string literal to the provided Writer.

Parameters:

  • W (Writer): A type conforming to the Writable trait.

Args:

  • writer (W): The object to write to.

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.

replace

replace(self, old: Self, new: Self) -> Self

Return a copy of the string with all occurrences of substring old if replaced by new. This operation only works in the param domain.

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.

join

join[T: StringableCollectionElement](self, elems: List[T, hint_trivial_type]) -> String

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.

join(self, *elems: Int) -> String

Joins the elements from the tuple using the current string literal as a delimiter.

Args:

  • *elems (Int): The input tuple.

Returns:

The joined string.

join[*Types: Stringable](self, *elems: *Types) -> String

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.

split

split(self, sep: String, maxsplit: Int = -1) -> List[String]

Split the string literal by a separator.

Examples:

# Splitting a space
_ = "hello world".split(" ") # ["hello", "world"]
# Splitting adjacent separators
_ = "hello,,world".split(",") # ["hello", "", "world"]
# Splitting with maxsplit
_ = "1,2,3".split(",", 1) # ['1', '2,3']
# Splitting a space
_ = "hello world".split(" ") # ["hello", "world"]
# Splitting adjacent separators
_ = "hello,,world".split(",") # ["hello", "", "world"]
# Splitting with maxsplit
_ = "1,2,3".split(",", 1) # ['1', '2,3']

.

Args:

  • sep (String): 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, sep: NoneType = None, maxsplit: Int = -1) -> List[String]

Split the string literal by every whitespace separator.

Examples:

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

# Splitting a string with leading, trailing, and middle whitespaces
_ = " hello world ".split() # ["hello", "world"]
# Splitting adjacent universal newlines:
_ = "hello \t\n\v\f\r\x1c\x1d\x1e\x85\u2028\u2029world".split()
# ["hello", "world"]
# Splitting an empty string or filled with whitespaces
_ = " ".split() # []
_ = "".split() # []

# Splitting a string with leading, trailing, and middle whitespaces
_ = " hello world ".split() # ["hello", "world"]
# Splitting adjacent universal newlines:
_ = "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 literal 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.

count

count(self, substr: String) -> 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 (String): The substring to count.

Returns:

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:

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:

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

rjust

rjust(self, width: Int, fillchar: Self = " ") -> String

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

Args:

  • width (Int): The width of the field containing the string.
  • fillchar (Self): 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: Self = " ") -> String

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

Args:

  • width (Int): The width of the field containing the string.
  • fillchar (Self): 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: Self = " ") -> String

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

Args:

  • width (Int): The width of the field containing the string.
  • fillchar (Self): Specifies the padding character.

Returns:

Returns center justified string, or self if width is not bigger than self length.

startswith

startswith(self, prefix: String, 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 (String): 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: String, 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 (String): 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.

isdigit

isdigit(self) -> Bool

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

Note that this currently only works with ASCII strings.

Returns:

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:

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:

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

strip

strip(self) -> String

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

Returns:

A string with no leading or trailing whitespaces.

strip(self, chars: String) -> String

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

Args:

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

Returns:

A string with no leading or trailing characters.

rstrip

rstrip(self, chars: String) -> String

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

Args:

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

Returns:

A string with no trailing characters.

rstrip(self) -> String

Return a copy of the string with trailing whitespaces removed.

Returns:

A copy of the string with no trailing whitespaces.

lstrip

lstrip(self, chars: String) -> String

Return a copy of the string with leading characters removed.

Args:

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

Returns:

A copy of the string with no leading characters.

lstrip(self) -> String

Return a copy of the string with leading whitespaces removed.

Returns:

A copy of the string with no leading whitespaces.