List

typedef struct {
    uint32_t length;
    uint32_t realLength;
    int8_t *type;
    unitype *data;
} list_t;

The list module or unitype list is a simple resizable array that can hold a variety of different types. It accomplishes this by using a union called unitype defined in list.h:

typedef union {
    signed char ch;
    bool bo;
    int8_t c;
    uint8_t b;
    int16_t h;
    uint16_t hu;
    int32_t i;
    uint32_t u;
    int64_t li;
    uint64_t l;
    float f;
    double d; // i will stand by it. d should be double
    double lf;
    char *s;
    void *p;
    list_t *r;
    list_t *list;
} unitype;

Note that the list uses stdint types like uint32_t rather than the standard C types like unsigned int. This is because standard C int types can have different sizes on different platforms.

Basic Functionality

A list is of type list_t * and is created with list_init()

list_t *newList = list_init(); // create a new list

To add items to the list, use list_append(). You'll need to cast your item to a unitype as well as provide the type^[1]

list_append(newList, (unitype) 0, 'i'); // adds 0 to the list as an integer

Rather than remember which characters correspond to which types (some of which are very unintuitive), you can use elements from the list_type_t enum defined in list.h:

typedef enum {
    LIST_TYPE_BOOL = 'b',
    LIST_TYPE_CHAR = 'c',
    LIST_TYPE_INT8 = 'e',
    LIST_TYPE_UINT8 = 'b',
    LIST_TYPE_INT16 = 'j',
    LIST_TYPE_UINT16 = 'h',
    LIST_TYPE_INT32 = 'i',
    LIST_TYPE_UINT32 = 'u',
    LIST_TYPE_INT64 = 'm',
    LIST_TYPE_UINT64 = 'l',
    LIST_TYPE_FLOAT = 'f',
    LIST_TYPE_DOUBLE = 'd',
    LIST_TYPE_STRING = 's',
    LIST_TYPE_POINTER = 'p',
    LIST_TYPE_LIST = 'r',
} list_type_t;

I recommend using these in list functions, but they are equivalent to the raw characters:

list_append(newList, (unitype) 0, LIST_TYPE_INT32); // adds 0 to the list as an integer

To get items out of a list, use

int32_t item = newList -> data[0].i; // get the 0th item of the list as an integer

For these, you'll need to use the names of the unitype elements, or you can simply cast your outputs to the desired type:

int32_t item = (int32_t) newList -> data[0]; // get the 0th item of the list as an integer

To get the length of a list, use

uint32_t listLength = newList -> length;

Keep in mind that the length is a uint32_t, meaning the list has a maximum of 4294967295 items^[3].

All Functions

Create a list:

list_t *newList = list_init(); // create a new list

Append to list:

list_append(newList, (unitype) 5.0, 'd'); // adds 5 to the list as an double
list_append(newList, (unitype) 5.0, LIST_TYPE_DOUBLE); // adds 5 to the list as an double

Print a list:

list_print(newList);

Print a list to a file (note you'll need an open file pointer - this function will not create a file):

list_fprint_emb(fp, list);

Insert to list:

list_insert(newList, 5, (unitype) "hello", 's'); // insert the string "hello" at position 5 of the list
list_insert(newList, 5, (unitype) "hello", LIST_TYPE_STRING); // insert the string "hello" at position 5 of the list

Clear the list:

list_clear(newList); // deletes all items from the list, but does not free it

Free a list:

list_free(newList); // deletes and frees the list

Delete an item from the list:

list_delete(newList, 3); // deletes the 3rd item of the list

Delete the last item of the list:

list_pop(newList); // deletes the last item of the list

Delete a range of items from the list:

list_delete_range(newList, 2, 5); // deletes items 2, 3, and 4 from the list

Find the index of an item in the list^[4]:

list_find(newList, (unitype) "hello", 's'); // return first index of "hello" in the list
list_find(newList, (unitype) "hello", LIST_TYPE_STRING); // return first index of "hello" in the list
list_index(newList, (unitype) "hello", 's'); // return first index of "hello" in the list
list_index(newList, (unitype) "hello", LIST_TYPE_STRING); // return first index of "hello" in the list

Count how many instances of a particular item in a list:

list_count(newList, (unitype) 10.0, 'd'); // return the number of times 10.0 is in the list
list_count(newList, (unitype) 10.0, LIST_TYPE_DOUBLE); // return the number of times 10.0 is in the list

Find and remove first instance of an item in a list^[4]:

list_remove(newList, (unitype) 256, 'i'); // removes the first instance of 256 in the list
list_remove(newList, (unitype) 256, LIST_TYPE_INT32); // removes the first instance of 256 in the list

Sort the list in place:

list_sort(newList);

Copy one list to another - note the destination list must have been created with list_init():

list_copy(sourceList, destinationList);

Print the types of a list:

list_print_type(newList);

Appendix

[0]: The list is not thread safe
[1]: Because casting to unions is not supported in C89 or in C++, the list module, and therefore the entire turtle library, will not work with those standards.
[2]: Since the list is an array of unitypes, which are 8 bytes on most platforms, the total memory size of a list is roughly its length * 9
[3]: Be careful when doing arithmetic using the list length. For example this code:

for (int32_t i = 0; i < list -> length - 1; i++) {
    ...
}

Will loop forever if the length of the list is 0.
[4]: Note that strict type checking is not done. If you try to find or remove an int32_t with value 5 it may find or remove a uint16_t with value 5. Strict type checking is only enabled for strings, pointers, and lists-within-lists.