ListHead

Documentation

API Reference

ListHead

Description

Direct O(1) reference to the head node, or NULL when the list is empty. Unlike ListNodeBegin (which aborts on empty), this is safe to call on an empty list and is meant for invariant checks like ListHead(&l) == NULL.

Parameters

Name	Direction	Description
`l`	in	List to query.

Success

Returns the head-node pointer.

Failure

Returns NULL when the list is empty. The list is not modified.

Usage example (Cross-references)

Usage examples (Cross-references)

In Ops.c:101:

        ListClear(&list);
    
        bool result = (ListLen(&list) == 0) && (ListHead(&list) == NULL) && (ListTail(&list) == NULL);
    
        ListPushBackR(&list, 9);

In Ops.c:151:

        ListReverse(&singleton);
    
        bool result = (ListLen(&empty) == 0) && (ListHead(&empty) == NULL) && (ListTail(&empty) == NULL);
        result      = result && list_matches(GENERIC_LIST(&singleton), (const int[]) {42}, 1);

In Ops.c:176:

        ListClear(&list);
        result = result && (g_copy_deinit_count == 2);
        result = result && (ListLen(&list) == 0) && (ListHead(&list) == NULL) && (ListTail(&list) == NULL);
    
        ListPushBackR(&list, 9);

In Init.c:108:

    
        result = result && (g_copy_deinit_count == 2);
        result = result && (ListHead(&list) == NULL) && (ListTail(&list) == NULL) && (ListLen(&list) == 0);
        // Verifying ListDeinit clears the hook fields.
        result = result && (ListCopyInit(&list) == NULL) && (ListCopyDeinit(&list) == NULL);

In Insert.c:198:

        bool result = (g_copy_init_count == 2);
        result      = result && list_matches(GENERIC_LIST(&dest), (const int[]) {1003, 1004}, 2);
        result      = result && (ListLen(&src) == 0) && (ListHead(&src) == NULL) && (ListTail(&src) == NULL);
        result      = result && (ListCopyInit(&src) == tracked_copy_init) && (ListCopyDeinit(&src) == tracked_copy_deinit);

In Insert.c:242:

    
        bool result = list_matches(GENERIC_LIST(&dest_l), (const int[]) {1, 2, 3, 4}, 4);
        result      = result && (ListLen(&src_l) == 0) && (ListHead(&src_l) == NULL) && (ListTail(&src_l) == NULL);
        result      = result && list_matches(GENERIC_LIST(&dest_r), (const int[]) {1, 2, 3, 4}, 4);
        result      = result && list_matches(GENERIC_LIST(&src_r), (const int[]) {3, 4}, 2);

In Insert.c:246:

        result      = result && list_matches(GENERIC_LIST(&src_r), (const int[]) {3, 4}, 2);
        result      = result && list_matches(GENERIC_LIST(&dest_a), (const int[]) {5, 6}, 2);
        result      = result && (ListLen(&src_a) == 0) && (ListHead(&src_a) == NULL) && (ListTail(&src_a) == NULL);
    
        ListDeinit(&dest_l);

In Type.c:29:

        // checks; no public accessor exposes it, so the layout test reads it
        // directly to confirm ListInit planted the right value.
        bool result = (ListHead(&list) == NULL) && (ListTail(&list) == NULL) && (ListCopyInit(&list) == NULL) &&
                      (ListCopyDeinit(&list) == NULL) && (ListLen(&list) == 0) && MAGIC_MATCHES(list.__magic, LIST_MAGIC);

In Remove.c:69:

        result = result && (removed == 40);
        result = result && list_matches(GENERIC_LIST(&list), (const int[]) {30}, 1);
        result = result && ListHead(&list) && ListNodeData(ListHead(&list)) && (*ListNodeData(ListHead(&list)) == 30);
        result = result && ListTail(&list) && ListNodeData(ListTail(&list)) && (*ListNodeData(ListTail(&list)) == 30);

In Remove.c:104:

    
        ListDeleteRange(&list, 0, 2);
        result = result && (ListLen(&list) == 0) && (ListHead(&list) == NULL) && (ListTail(&list) == NULL);
    
        ListDeinit(&list);

In Remove.c:135:

        result = result && (suffix[0] == 5) && (suffix[1] == 6);
        result = result && list_matches(GENERIC_LIST(&list), (const int[]) {3, 4}, 2);
        result = result && ListHead(&list) && ListNodeData(ListHead(&list)) && (*ListNodeData(ListHead(&list)) == 3);
        result = result && ListTail(&list) && ListNodeData(ListTail(&list)) && (*ListNodeData(ListTail(&list)) == 4);

In Remove.c:158:

    
        bool result = (removed[0] == 7) && (removed[1] == 8) && (removed[2] == 9);
        result      = result && (ListLen(&list) == 0) && (ListHead(&list) == NULL) && (ListTail(&list) == NULL);
    
        ListDeinit(&list);

In Remove.c:197:

        ListClear(&list);
        result = result && (g_copy_deinit_count == 2);
        result = result && (ListLen(&list) == 0) && (ListHead(&list) == NULL) && (ListTail(&list) == NULL);
    
        ListDeinit(&list);

In Access.c:80:

        result = result && (ListLen(&list) == 0);
        result = result && ListEmpty(&list);
        result = result && (ListHead(&list) == NULL) && (ListTail(&list) == NULL);
    
        ListPushBackR(&list, 30);

Last updated on July 1, 2026

ListForeachReverseInRange ListInit