IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /docs/manual/basics.md). For the complete Mojo documentation index, see llms.txt.
Skip to main content
Version: Nightly
For the complete Mojo documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md).

CStringSpan

struct CStringSpan[origin: ImmOrigin]

A non-owning immutable view to a nul-terminated C string (const char*).

This type can be safely constructed from any sort of StringSpan or Span[Byte] that is nul-terminated, or unsafely from a raw pointer.

Parameters​

  • ​origin (ImmOrigin): The origin of the CStringSpan.

Implemented traits​

AnyType, Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, Sized, TrivialRegisterPassable, UnsafeNicheable, Writable

Methods​

__init__​

def __init__(*, unsafe_from_ptr: Pointer[Int8, origin]) -> Self

Construct a CStringSpan from a Pointer.

Safety: The Pointer must be a valid nul-terminated C string. The pointer cannot be null. To represent nullability, use Optional[CStringSpan].

Example:

from std.ffi import c_char, CStringSpan, external_call

def getenv_wrapper(
    name: CStringSpan,
) raises -> CStringSpan[ImmStaticOrigin]:
    # External call to 'getenv'.
    # C signature: const char *getenv(const char *name);
    var result = external_call[
        "getenv",
        Optional[CStringSpan[ImmStaticOrigin]],
    ](name)

    try:
        # Optional.__getitem__ raises an error if empty.
        return result[]
    except:
        raise Error("getenv returned an error!")

Args:

def __init__(out self, span: StringSpan[origin])

Construct a CStringSpan from a StringSpan.

Example:

from std.ffi import CStringSpan
from std.testing import assert_raises

var string = String("Hello, World!")

with assert_raises():
    # This will raise an error since the string is not nul-terminated.
    _ = CStringSpan(string)

Args:

Raises:

An error if the span is not nul-terminated or has interior nul bytes.

def __init__(out self, span: Span[UInt8, origin])

Construct a CStringSpan from a Span[Byte].

Args:

Raises:

An error if the span is not nul-terminated or has interior nul bytes.

__eq__​

def __eq__(self, rhs_same: Self) -> Bool

Compare two CStringSpans for equality.

Args:

  • ​rhs_same (Self): The CStringSpan to compare against.

Returns:

Bool: True if the CStringSpans are equal, False otherwise.

def __eq__(self, rhs: CStringSpan) -> Bool

Compare two CStringSpans for equality.

Args:

  • ​rhs (CStringSpan): The CStringSpan to compare against.

Returns:

Bool: True if the CStringSpans are equal, False otherwise.

__ne__​

def __ne__(self, rhs: CStringSpan) -> Bool

Compare two CStringSpans for inequality.

Args:

  • ​rhs (CStringSpan): The CStringSpan to compare against.

Returns:

Bool: True if the CStringSpans are not equal, False otherwise.

__len__​

def __len__(self) -> Int

Get the length of the C string. Like C's strlen this does not include the nul terminator.

Returns:

Int: The length of the C string.

write_to​

def write_to(self, mut writer: T)

Write the CStringSpan to a Writer, the nul terminator is omitted.

Args:

  • ​writer (T): The Writer to write the CStringSpan to.

write_repr_to​

def write_repr_to(self, mut writer: T)

Write the string representation of this CStringSpan to a Writer.

Args:

  • ​writer (T): The Writer to write the CStringSpan to.

ptr​

def ptr(self) -> Pointer[Int8, origin]

Get a pointer to the underlying CStringSpan.

Returns:

Pointer[Int8, origin]: A pointer to the underlying CStringSpan.

as_bytes​

def as_bytes(self) -> Span[UInt8, origin]

Get a span of the underlying CStringSpan as bytes.

The returned span does not include the nul terminator. If you want a byte span including the nul terminator, use as_bytes_with_nul().

Returns:

Span[UInt8, origin]: A span of the underlying CStringSpan as bytes.

as_bytes_with_nul​

def as_bytes_with_nul(self) -> Span[UInt8, origin]

Get a span of the underlying CStringSpan as bytes including the nul terminator.

If you want a byte span not including the nul terminator, use as_bytes().

Returns:

Span[UInt8, origin]: A span of the underlying CStringSpan as bytes.

View source