StrIndexOf

Documentation

API Reference

StrIndexOf

Description

Find the index of the first occurrence of a key inside a Str.

Three call shapes via OVERLOAD + _Generic on key: StrIndexOf(s, key) – key is Str * or Zstr. StrIndexOf(s, key, key_len) – key is a fixed-length view (Zstr, size). An empty key matches at position 0.

Parameters

Name	Direction	Description
`s`	in	Str object to search in.
`key`	in	Substring to search for (`Str *` / `Zstr`).
`key_len`	in	Length of `key` when using the 3-arg fixed-length form.

Success

Returns the zero-based index of the first match. The string is not modified.

Failure

Returns SIZE_MAX when no match is found. The string is not modified.

Usage example (Cross-references)

Usage examples (Cross-references)

In Ops.c:100:

    // Test string contains/index functions
    bool test_str_contains_index(void) {
        WriteFmt("Testing StrContains and StrIndexOf variants\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:110:

        result      = result && StrContains(&haystack, "Hello");
        result      = result && StrContains(&haystack, "lo Wo", 5);
        result      = result && (StrIndexOf(&haystack, &needle) == 6);
        result      = result && (StrIndexOf(&haystack, "Hello") == 0);
        result      = result && (StrIndexOf(&haystack, "World", 5) == 6);

In Ops.c:111:

        result      = result && StrContains(&haystack, "lo Wo", 5);
        result      = result && (StrIndexOf(&haystack, &needle) == 6);
        result      = result && (StrIndexOf(&haystack, "Hello") == 0);
        result      = result && (StrIndexOf(&haystack, "World", 5) == 6);
        result      = result && !StrContains(&haystack, "missing");

In Ops.c:112:

        result      = result && (StrIndexOf(&haystack, &needle) == 6);
        result      = result && (StrIndexOf(&haystack, "Hello") == 0);
        result      = result && (StrIndexOf(&haystack, "World", 5) == 6);
        result      = result && !StrContains(&haystack, "missing");
        result      = result && (StrIndexOf(&haystack, "missing") == SIZE_MAX);

In Ops.c:114:

        result      = result && (StrIndexOf(&haystack, "World", 5) == 6);
        result      = result && !StrContains(&haystack, "missing");
        result      = result && (StrIndexOf(&haystack, "missing") == SIZE_MAX);
        result      = result && StrContains(&haystack, "");
        result      = result && (StrIndexOf(&haystack, "") == 0);

In Ops.c:116:

        result      = result && (StrIndexOf(&haystack, "missing") == SIZE_MAX);
        result      = result && StrContains(&haystack, "");
        result      = result && (StrIndexOf(&haystack, "") == 0);
    
        StrDeinit(&haystack);

In Ops.c:573:

    // to SIZE_MAX.
    static bool test_index_of_whole_string(void) {
        WriteFmt("Testing StrIndexOf matches a key equal to the whole string\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:578:

        Str s = StrInitFromZstr("abc", &alloc);
    
        bool result = (StrIndexOf(&s, "abc", 3) == 0);
        if (!result) {
            WriteFmt("    FAIL: Expected index 0 for whole-string key\n");

In Ops.c:806:

    // corrupted key must abort (s is valid) (Str.Mutants5).
    static bool test_str_index_of_str_corrupt_key_aborts(void) {
        WriteFmt("Testing StrIndexOf validates key (should abort)\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:817:

        MAGIC_MARK_DIRTY(&key);
    
        (void)StrIndexOf(&s, &key); // Str* -> str_index_of_str; should abort here
    
        return false;               // unreachable on real code

In Ops.c:973:

    // abort (Str.Mutants7).
    static bool test_index_of_validates(void) {
        WriteFmt("Testing StrIndexOf validates its Str (deadend)\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:978:

        Str s     = StrInitFromZstr("abc", &alloc);
        s.__magic = 0;
        size idx  = StrIndexOf(&s, "x", 1);
        (void)idx;

Last updated on July 1, 2026

StrFromU64 StrInit