Skip to main content

/

Docs

Nightly

v24.6

Log in

Mojo struct

StringRef

@register_passable(trivial) struct StringRef

Represent a constant reference to a string, i.e. a sequence of characters and a length, which need not be null terminated.

Fields​

  • ​data (UnsafePointer[SIMD[uint8, 1]]): A pointer to the beginning of the string data being referenced.
  • ​length (Int): The length of the string being referenced.

Implemented traits​

AnyType, AsBytes, Boolable, CollectionElement, CollectionElementNew, Comparable, Copyable, EqualityComparable, ExplicitlyCopyable, Hashable, IntableRaising, Movable, Representable, Sized, Stringable, UnknownDestructibility, Writable, _HashableWithHasher

Methods​

__init__​

__init__(out self)

Construct a StringRef value with length zero.

__init__(out self, *, other: Self)

Copy the object.

Args:

  • ​other (Self): The value to copy.

@implicit __init__(out self, str: StringLiteral)

Construct a StringRef value given a constant string.

Args:

  • ​str (StringLiteral): The input constant string.

__init__(out self, ptr: UnsafePointer[SIMD[int8, 1]], len: Int)

Construct a StringRef value given a (potentially non-0 terminated string).

The constructor takes a raw pointer and a length.

Note that you should use the constructor from UnsafePointer[UInt8] instead as we are now storing the bytes as UInt8. See https://github.com/modularml/mojo/issues/2317 for more information.

Args:

  • ​ptr (UnsafePointer[SIMD[int8, 1]]): UnsafePointer to the string.
  • ​len (Int): The length of the string.

__init__(out self, *, ptr: UnsafePointer[SIMD[uint8, 1]])

Construct a StringRef value given a null-terminated string.

Args:

  • ​ptr (UnsafePointer[SIMD[uint8, 1]]): UnsafePointer to the string.

@implicit __init__(out self, ptr: UnsafePointer[SIMD[int8, 1]])

Construct a StringRef value given a null-terminated string.

Note that you should use the constructor from UnsafePointer[UInt8] instead as we are now storing the bytes as UInt8. See https://github.com/modularml/mojo/issues/2317 for more information.

Args:

  • ​ptr (UnsafePointer[SIMD[int8, 1]]): UnsafePointer to the string.

__bool__​

__bool__(self) -> Bool

Checks if the string is empty or not.

Returns:

Returns True if the string is not empty and False otherwise.

__getitem__​

__getitem__(self, idx: Int) -> Self

Get the string value at the specified position.

Args:

  • ​idx (Int): The index position.

Returns:

The character at the specified position.

__lt__​

__lt__(self, rhs: Self) -> Bool

Compare this StringRef to the RHS using LT comparison.

Args:

  • ​rhs (Self): The other StringRef 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 StringRef to the RHS using LE comparison.

Args:

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

Returns:

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

__eq__​

__eq__(self, rhs: Self) -> Bool

Compares two strings are equal.

Args:

  • ​rhs (Self): The other string.

Returns:

True if the strings match and False otherwise.

__ne__​

__ne__(self, rhs: Self) -> Bool

Compares two strings are not equal.

Args:

  • ​rhs (Self): The other string.

Returns:

True if the strings do not match and False otherwise.

__gt__​

__gt__(self, rhs: Self) -> Bool

Compare this StringRef to the RHS using GT comparison.

Args:

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

Returns:

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

__ge__​

__ge__(self, rhs: Self) -> Bool

Compare this StringRef to the RHS using GE comparison.

Args:

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

Returns:

True if this string is greater than or equal to the RHS string 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.

take_front​

take_front(self, num_bytes: Int = 1) -> Self

Return a StringRef equal to 'self' but with only the first num_bytes elements remaining. If num_bytes is greater than the length of the string, the entire string is returned.

Args:

  • ​num_bytes (Int): The number of bytes to include.

Returns:

A new slice that starts with those bytes.

take_back​

take_back(self, num_bytes: Int = 1) -> Self

Return a StringRef equal to 'self' but with only the last num_bytes elements remaining. If num_bytes is greater than the length of the string, the entire string is returned.

Args:

  • ​num_bytes (Int): The number of bytes to include.

Returns:

A new slice that ends with those bytes.

drop_front​

drop_front(self, num_bytes: Int = 1) -> Self

Return a StringRef equal to 'self' but with the first num_bytes elements skipped. If num_bytes is greater than the length of the string, an empty StringRef is returned.

Args:

  • ​num_bytes (Int): The number of bytes to drop.

Returns:

A new slice with those bytes skipped.

drop_back​

drop_back(self, num_bytes: Int = 1) -> Self

Return a StringRef equal to 'self' but with the last num_bytes elements skipped. If num_bytes is greater than the length of the string, the entire string is returned.

Args:

  • ​num_bytes (Int): The number of bytes to include.

Returns:

A new slice ends earlier than those bytes.

as_bytes​

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

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

Returns:

A contiguous slice pointing to the bytes owned by this 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.

__int__​

__int__(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.

__len__​

__len__(self) -> Int

Returns the length of the string.

Returns:

The length of the string.

__str__​

__str__(self) -> String

Convert the string reference to a string.

Returns:

A new string.

__repr__​

__repr__(self) -> String

Convert the string reference to a string.

Returns:

The String representation of the StringRef.

write_to​

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

Formats this StringRef to the provided Writer.

Parameters:

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

Args:

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

__fspath__​

__fspath__(self) -> String

Return the file system path representation of the object.

Returns:

The file system path representation as a string.

unsafe_ptr​

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

Retrieves a pointer to the underlying memory.

Returns:

The pointer to the underlying memory.

empty​

empty(self) -> Bool

Returns True if the StringRef has length = 0.

Returns:

Whether the stringref is empty.

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.

strip​

strip(self) -> Self

Gets a StringRef with leading and trailing whitespaces removed. This only takes C spaces into account: " \t\n\v\f\r".

For example, " mojo " returns "mojo".

Returns:

A StringRef with leading and trailing whitespaces removed.

split​

split(self, delimiter: Self) -> List[StringRef]

Split the StringRef by a delimiter.

Args:

  • ​delimiter (Self): The StringRef to split on.

Returns:

A List of StringRefs containing the input split by the delimiter.

Raises:

Error if an empty delimiter is specified.