StrContains

Documentation

API Reference

StrContains

Description

Check whether a Str contains a key.

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

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 true when a match exists. The string is not modified.

Failure

Returns false. 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:107:

        Str needle   = StrInitFromZstr("World", &alloc);
    
        bool result = StrContains(&haystack, &needle);
        result      = result && StrContains(&haystack, "Hello");
        result      = result && StrContains(&haystack, "lo Wo", 5);

In Ops.c:108:

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

In Ops.c:109:

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

In Ops.c:113:

        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);
        result      = result && StrContains(&haystack, "");

In Ops.c:115:

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

In Ops.c:429:

    // not a substring must report false via the Str* path.
    static bool test_contains_str_absent_key_false(void) {
        WriteFmt("Testing StrContains(Str*) absent key is false\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:434:

        Str  haystack = StrInitFromZstr("Hello World", &alloc);
        Str  needle   = StrInitFromZstr("missing", &alloc);
        bool result   = (StrContains(&haystack, &needle) == false);
    
        StrDeinit(&needle);

In Ops.c:447:

    // constant replacement.
    static bool test_contains_str_present_and_absent(void) {
        WriteFmt("Testing StrContains(Str*) present vs absent\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:453:

        Str  present  = StrInitFromZstr("World", &alloc);
        Str  absent   = StrInitFromZstr("missing", &alloc);
        bool result   = (StrContains(&haystack, &present) == true) && (StrContains(&haystack, &absent) == false);
    
        StrDeinit(&absent);

In Ops.c:466:

    // key reports contained. An absent key via the Cstr/Zstr path must be false.
    static bool test_contains_cstr_absent_key_false(void) {
        WriteFmt("Testing StrContains(Zstr) absent key is false\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:470:

    
        Str  haystack = StrInitFromZstr("Hello World", &alloc);
        bool result   = (StrContains(&haystack, "missing") == false);
    
        StrDeinit(&haystack);

In Ops.c:852:

    // corrupt key magic must abort (Str.Mutants6).
    static bool test_contains_str_corrupt_key_magic_aborts(void) {
        WriteFmt("Testing StrContains aborts on corrupt key magic\n");
        DefaultAllocator alloc = DefaultAllocatorInit();

In Ops.c:858:

        Str key                     = StrInitFromZstr("World", &alloc);
        GENERIC_VEC(&key)->__magic ^= 0x1;
        (void)StrContains(&haystack, &key);
    
        GENERIC_VEC(&key)->__magic ^= 0x1;

Last updated on July 1, 2026

StrCmpIgnoreCase StrContainsChar