Skip to main content
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.

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

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

startswith

startswith(self, prefix: Self, start: Int = 0, end: Int = -1) -> Bool

Checks if the StringRef 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 StringRef 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.