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. NULL iff the list is empty.

Usage example (Cross-references)

Usage examples (Cross-references)

In List.Ops.c:63:

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

In List.Ops.c:113:

        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 List.Ops.c:138:

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

In List.Type.c:17:

        ValidateList(&list);
    
        bool result = (ListHead(&list) == NULL) && (ListTail(&list) == NULL) && (list.copy_init == NULL) &&
                      (list.copy_deinit == NULL) && (ListLen(&list) == 0) && (list.__magic == LIST_MAGIC);

In List.Init.c:105:

    
        result = result && (g_copy_deinit_count == 2);
        result = result && (ListHead(&list) == NULL) && (ListTail(&list) == NULL) && (ListLen(&list) == 0);
        result = result && (list.copy_init == NULL) && (list.copy_deinit == NULL);
        DefaultAllocatorDeinit(&alloc);

In List.Access.c:49:

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

In List.Remove.c:69:

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

In List.Remove.c:104:

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

In List.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) && ListHead(&list)->data && (*ListHead(&list)->data == 3);
        result = result && ListTail(&list) && ListTail(&list)->data && (*ListTail(&list)->data == 4);

In List.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 List.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 List.Insert.c:161:

        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 && (src.copy_init == tracked_copy_init) && (src.copy_deinit == tracked_copy_deinit);

In List.Insert.c:205:

    
        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 List.Insert.c:209:

        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);

Last updated on May 22, 2026

ListForeachReverseInRange ListInit