class std.List

Overview

This class provides a doubly linked list container for variant_t values. More…

import "std_List.jnc"

class List {
    // fields

    std.ListEntry* readonly m_head;
    std.ListEntry* readonly m_tail;
    size_t readonly m_count;

    // methods

    void clear();
    void takeOver(std.List* list);
    std.ListEntry* errorcode add(variant_t data);
    std.ListEntry* errorcode insertHead(variant_t data);
    std.ListEntry* errorcode insertTail(variant_t data);

    std.ListEntry* errorcode insertBefore(
        variant_t item,
        std.ListEntry* before
    );

    std.ListEntry* errorcode insertAfter(
        variant_t item,
        std.ListEntry* before
    );

    void moveToHead(std.ListEntry* entry);
    void moveToTail(std.ListEntry* entry);

    void moveBefore(
        std.ListEntry* entry,
        std.ListEntry* before
    );

    void moveAfter(
        std.ListEntry* entry,
        std.ListEntry* before
    );

    variant_t removeHead();
    variant_t removeTail();
    variant_t remove(std.ListEntry* entry);
};

Detailed Documentation

This class provides a doubly linked list container for variant_t values.

A typical sequence of steps when working with a doubly linked list usually looks like this:

Add items using insert methods: insertHead, insertTail, insertBefore, insertAfter;
Remove items using remove methods: removeHead, removeTail, removeBefore, removeAfter, remove;
Iterate over items by starting with m_head or m_tail and then move to the next element by inspecting std.ListEntry.m_next or std.ListEntry.m_prev.

Sample code:

std.List list;

// add items...

int a[] = { 10, 20, 30, 40, 50, }

for (size_t i = 0; i < countof(a); i++)
    list.insertTail(a[i]);

// iterate over list...

std.ListEntry* e = list.m_head;
for (; e; e = e.m_next) {
    // access e.m_data...
}

Fields

std.ListEntry* readonly m_head

Holds a pointer to the list head (the first element of the list) or null if the list is empty.

std.ListEntry* readonly m_tail

Holds a pointer to the list tail (the last element of the list) or null if the list is empty.

size_t readonly m_count

Holds number of elements on the list.

Methods

void clear()

Removes all elements from the lists.

void takeOver(std.List* list)

Moves all the elements from the source list list to this list.

After the take-over, list will be empty and this list will contain the same elements as list originally did.

This operation is performed in constant time no matter the size of the source list – so it’s always more efficient than clearing the list first and then adding all the items from the source list in a loop.

std.ListEntry* errorcode add(variant_t data)

Adds item data to the list.