This library provides a Python-style (within the limits of the C language syntax of course) lists implementation, as doubly-linked lists:
- List items are ordered, changeable, and allow duplicate values.
- List items can be of any standard C data type, plus:
- strings,
- sub-lists (thus enabling trees data structures)
- and self-contained (= without pointers) structs of variable sizes.
- A list can contain different data types at the same time.
Beyond Python lists emulation, you'll also find:
- List initialization with a powerful constructor or from C language tables
- Conversion from or to arrays
- List deduplication, sorted insertion (with optional removal of duplicate values) or shuffling
- List joining (beyond concatenation or extension) or splitting
- Stacks (push/pop) and queues (enqueue/dequeue) management aliases
- Statistics and debugging, including memory allocation followup
With:
- Over 60 base functions,
- Plus over 320 convenience type-oriented functions and intuitive aliases,
- High modularity so your linker only includes what you use in your own executables,
- Identical behavior across Unix-like and Windows operating systems for your programs portability,
- Extensive documentation with examples for almost everything,
- And friendly BSD license, for open and free usage.
| Base function | Aliases | Description |
|---|---|---|
| Creating a list | ||
| LIST* MyList = NULL; | Creates an empty LIST | |
| listCreateElement() | Creates an unlinked LIST element (rather for internal use) | |
| list() | Creates a LIST from a Python-style LIST declaration string | |
| listFromTable() | Converts a C language table into a LIST | |
| Adding & changing elements | ||
| listAppend() | listPush() listEnqueue() |
Adds an element at the end of a LIST |
| listInsertFirst() | listPrepend() | Adds an element at the start of a LIST |
| listInsert(n) | Inserts an element at the Nth position of a LIST | |
| listInsertSorted() | Inserts an element in a sorted LIST | |
| listInsertList(n) | Inserts a copy of the elements of a LIST at the Nth position of another LIST | |
| listChange(n) | Changes the value of the element at the Nth position of a LIST | |
| listChangeSlice(n, m) | Changes the elements at the defined LIST slice with those from the second LIST | |
| Displaying lists | ||
| listStr() | listAscii() listRepr() |
Returns a pointer to a string containing a Python-style LIST representation |
| listFreeStr() | Frees the memory allocated to a Python-style LIST representation | |
| listPrint() | Prints a Python-style LIST representation to stdout | |
| listDebug() | Prints all LIST details to stderr | |
| Getting list information | ||
| listLen() | Returns the number of elements in a LIST | |
| listStats() | Fills statistics about a LIST in one walkthrough | |
| listStatsPrint() | Prints statistics about a LIST to stdout | |
| Searching for elements | ||
| listContains() | Tests if a value appears in a LIST | |
| listCount() | Returns the number of elements with the specified value | |
| listIndex() | Returns the index of the first element with the specified value | |
| listIndexAll() | listFind() listSearch() |
Returns a LIST of all the indexes of the elements with the specified value |
| Working with numerical lists | ||
| listMaxXXX() | Returns the maximum value in the LIST for the XXX type | |
| listMinXXX() | Returns the minimum value in the LIST for the XXX type | |
| listSumXXX() | Returns the sum of values in the LIST for the XXX type | |
| Fetching elements | ||
| listGet(n) | Returns the Nth LIST_ELEMENT of a LIST | |
| listGetLast() | Returns the last LIST_ELEMENT of a LIST | |
| listSetIterator() | Defines a LIST_ITERATOR from a LIST_ELEMENT of a LIST | |
| listNext() | Returns the next LIST_ELEMENT of a LIST starting from a LIST_ITERATOR | |
| listPrevious() | Returns the previous LIST_ELEMENT of a LIST starting from a LIST_ITERATOR | |
| Fetching elements values | ||
| listValueXXX() | Returns the element value in the requested type | |
| Testing lists | ||
| listAreEqual() | Tests if two LISTs contain the same values | |
| Working with lists | ||
| listCopy() | Returns a copy of the LIST (a full/deep copy as we don't want multiple references to the same values) | |
| listSlice(n, m) listSliceFrom(n) listSliceTo(m) |
Returns a copy of a slice (i.e.: [n:m]) of a LIST | |
| listFilter() | Returns a filtered copy of the LIST according to a user defined function telling if a LIST_ELEMENT should be included or not | |
| listComprehension() | listForEach() | Returns a new LIST according to a user defined function producing 0-N elements for each LIST_ELEMENT |
| listConcat() | Returns a new LIST with the concatenation of the elements of LIST1 and LIST2 | |
| listExtend() | Adds a copy of the elements of the second LIST to the end of the first one | |
| listJoin() | Moves the elements of the second LIST to the end of the first one | |
| listSplit(n) | listHalve() for n = length/2 | Cuts a LIST in two parts and returns a pointer to the second part |
| Changing list order | ||
| listSort() | Sorts a LIST | |
| listSorted() | Returns a sorted copy of a LIST | |
| listSetDefaultSort() | Sets the default sorting algorithm | |
| listSortedByInsertion() | Returns a sorted copy of a LIST, using an insertion sort algorithm | |
| listSortedByQsort() | Returns a sorted copy of a LIST, using a Quicksort algorithm | |
| listReverse() | Reverses the order of a LIST | |
| listReversed() | Returns a reversed copy of a LIST | |
| listShuffle() | Shuffles a LIST | |
| listShuffled() | Returns a shuffled copy of a LIST | |
| Lists to arrays conversion | ||
| listToArray() | Converts a LIST into an ARRAY | |
| listFromArray() | Converts an ARRAY into a LIST | |
| listFreeArray() | Frees the memory allocated to an ARRAY | |
| Removing elements | ||
| listDelNth(n) | listDelFirst() for n=0 listDelLast() for n=-1 |
Removes the element at the specified position |
| listDelSlice(n, m) | Removes the elements at the specified slice | |
| listPopNth(n) | listPopFirst() for n=0 listDequeue() for n=0 listPop() for n=-1 |
Removes the element at the specified position and returns it (you'll have to free it after use with listClear()) |
| listRemove() | Removes the first item with the specified value | |
| listRemoveAll() | Removes all the items with the specified value | |
| listRemoveDuplicates() | Removes adjacent duplicate items in a sorted LIST | |
| Clearing lists | ||
| listClear() | listDel() listFree() |
Removes all the elements of the LIST |
| Structs handling | ||
| listSetStructSize() | Sets the size of a STRUCT you want to compare | |
| listSetStructComparator() | Sets the function to be used to compare STRUCTs | |
| listSetStructStringer() | Sets the function to be used to string STRUCTs | |
| listSetStructPrinter() | Sets the function to be used to print STRUCTs to stdout | |
| listSetStructDebugger() | Sets the function to be used to debug STRUCTs to stderr | |
| Miscellaneous | ||
| listSetDebugMessagesDisplay() | Sets whether or not to print debugging messages to stderr | |
| listSetFatalMallocErrors() | Sets whether memory allocation errors are fatal or not | |
| listGetAllocatedMemory() | Returns the quantity of allocated/unfreed memory used by this library |
Interested? Then go to the documentation to learn more about this library and find multiple examples.
Still missing something? Then go to the discussions and tell me!
Encountering an issue? Then report it in the issues section.
Happy with it? Then please help me promote this library.
- Go, tell it on the mountain(s), over the hills and everywhere!
- If your code is also on GitHub, reference and co-promote your own creations with the pylists4c topic
Volunteering to contribute? Then check our evolution ideas. For example:
- Make a package for your favourite operating system
- Translate the documentation
- Help with missing features and evolution ideas
- ...