'''
An exploration of Phil Bagwell's VList.

A VList is modeled as a 5-tuple:
    base: VList
    offset: int, indexing (from 0) the base VList data list.
    size: int, length of the data list.
    last_used: to make a mutable int it's an int in a list
               It's a count here rather than an offset!
               That is, it starts from 1, rather than 0.
    data: a list of length size.

A pointer to a VList is a two-tuple of (VList, offset) where
the offset is an index into the VList's data list.
'''


def cons(thing, vlist_ptr):
    if not vlist_ptr:
        return ((), 0, 1, [1], [thing]), 0

    (base, _offset, size, last_used_list, data), pointer_offset = vlist_ptr
    [last_used] = last_used_list

    '''
    > During the consing of (9) the pointer offset is compared with the
    last used offset, LastUsed. If it is the same and less than the block
    size then it is simply incremented, the new entry made and LastUsed
    updated.
    '''

    if pointer_offset == last_used - 1 and last_used < size:
        pointer_offset += 1
        data[pointer_offset] = thing
        last_used_list[0] = last_used + 1
        return vlist_ptr[0], pointer_offset