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], 0]): A pointer to the beginning of the string data being referenced.
• ​length (Int): The length of the string being referenced.

Implemented traits

AnyType, Boolable, CollectionElement, Comparable, Copyable, EqualityComparable, Hashable, IntableRaising, Movable, Sized, Stringable

Methods

__init__

__init__() -> Self

Construct a StringRef value with length zero.

Returns:

Constructed StringRef object.

__init__(str: StringLiteral) -> Self

Construct a StringRef value given a constant string.

Args:

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

Returns:

Constructed StringRef object.

__init__(ptr: DTypePointer[int8, 0], len: Int) -> Self

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 DTypePointer[DType.uint8] instead as we are now storing the bytes as UInt8. See https://github.com/modularml/mojo/issues/2317 for more information.

Args:

• ​ptr (DTypePointer[int8, 0]): DTypePointer to the string.
• ​len (Int): The length of the string.

Returns:

Constructed StringRef object.

__init__(ptr: DTypePointer[uint8, 0], len: Int) -> Self

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

The constructor takes a raw pointer and a length.

Args:

• ​ptr (DTypePointer[uint8, 0]): DTypePointer to the string.
• ​len (Int): The length of the string.

Returns:

Constructed StringRef object.

__init__(ptr: UnsafePointer[SIMD[uint8, 1], 0]) -> Self

Construct a StringRef value given a null-terminated string.

Args:

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

Returns:

Constructed StringRef object.

__init__(ptr: DTypePointer[int8, 0]) -> Self

Construct a StringRef value given a null-terminated string.

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

Args:

• ​ptr (DTypePointer[int8, 0]): DTypePointer to the string.

Returns:

Constructed StringRef object.

__init__(ptr: DTypePointer[uint8, 0]) -> Self

Construct a StringRef value given a null-terminated string.

Args:

• ​ptr (DTypePointer[uint8, 0]): DTypePointer to the string.

Returns:

Constructed StringRef object.

__bool__

__bool__(self: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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.

unsafe_ptr

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

Retrieves a pointer to the underlying memory.

Prefer to use as_uint8_ptr() instead.

Returns:

The pointer to the underlying memory.

empty

empty(self: Self) -> Bool

Returns True if the StringRef has length = 0.

Returns:

Whether the stringref is empty.

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.

strip

strip(self: Self) -> Self

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

For example, " mojo " returns "mojo".

Returns:

A StringRef with leading and trailing whitespaces removed.

startswith

startswith(self: 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: 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.