admin/C-Macro-Collections
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
911f7bf36fa507812137b6c87f10550ab34af637
C-Macro-Collections/Documentation.md
T
Leonardo 06b0a8c022 Added Documentation.md
2019-04-02 01:20:45 -03:00

12 KiB
Raw Blame History

Collections Documentation

List

A contiguous growable array. Elements can be added and removed from both ends of the array and also in the middle. This list can also be used to implement other data structures like stack, queues and deques, although queues and deques are implemented as a circular buffer, therefore being more efficient.

Generation Macro

  • LIST_GENERATE(PFX, SNAME, FMOD, V)
    • PFX - Functions namespace or prefix.
    • SNAME - Structure name.
    • FMOD - Function modifier (static or empty).
    • V - Element type.

Defined Structures

  • struct SNAME##_s - Structure Name (represents a list structure)
    • V *buffer - Internal storage.
    • size_t capacity - Storage capacity.
    • size_t count - Total elements in the list.
  • struct SNAME##_iter_s - Structure Iterator (represents a list iterator)
    • struct SNAME##_s *target - List being iterated over.
    • size_t cursor - Index pointing to the next or previous element in the iteration.
    • bool start - If the iterator reached the start of the list.
    • bool end - If the iterator reached the end of the list.

Typedefs

  • typedef struct SNAME##_s SNAME
  • typedef struct SNAME##_iter_s SNAME##_iter

Defined Functions

_new()

Allocates and returns a new list with an internal capacity of size. If allocation fails, NULL is returned.

Declaration

FMOD SNAME *PFX##_new(size_t size);

Parameters

  1. size_t size - The initial capacity for the list.

Returns

  1. SNAME * - A pointer to a heap allocated list.
  2. NULL - If allocation fails.

Complexity

  • O(1)

_free()

Frees from memory the list internal buffer and the structure itself. Note that if the elements inside the list are pointers to allocated memory, this function might cause memory leaks as it does not deals with its elements.

Declaration

FMOD void PFX##_free(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list to be freed from memory.

Complexity

  • O(1)

_push_front()

Shifts all elements one position to the right and adds an element at the front of the list (index 0).

Declaration

FMOD bool PFX##_push_front(SNAME *_list_, V element);

Parameters

  1. SNAME *_list_ - Target list.
  2. V element - Element to be added.

Returns

  1. true - If the element was successfully added to the list.
  2. false - If buffer reallocation failed.

Complexity

  • O(n)

_push()

Adds an element at a given index in the list. After it is successfully added to the list, the element is accessible at the index passed to the function.

Declaration

FMOD bool PFX##_push(SNAME *_list_, V element, size_t index);

Parameters

  1. SNAME *_list_ - Target list.
  2. V element - Element to be added.
  3. size_t index - Index to add the new element.
    • Can't be greater than the list count.

Returns

  1. true - If the element was successfully added to the list.
  2. false - If buffer reallocation failed, or if index is greater than the list count.

Complexity

  • O(n)

_push_back()

Adds an element at the back of the list (index count where count is the amount of elements in the list). No shifts are required.

Declaration

FMOD bool PFX##_push_back(SNAME *_list_, V element);

Parameters

  1. SNAME *_list_ - Target list.
  2. V element - Element to be added.

Returns

  1. true - If the element was successfully added to the list.
  2. false - If buffer reallocation failed.

Complexity

  • O(1)

_pop_front()

Removes the first element in the list (located at index 0) and shifts all remaining elements to the left.

Declaration

FMOD bool PFX##_pop_front(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. true - If the element was successfully removed from the list.
  2. false - If the list is empty.

Complexity

  • O(n)

_pop()

Removes the element located at a given index and shifts all the elements to its right to the left.

Declaration

FMOD bool PFX##_pop(SNAME *_list_, size_t index);

Parameters

  1. SNAME *_list_ - Target list.
  2. size_t index - The index of the element to be removed.
    • Can't be greater than or equal to the list count.

Returns

  1. true - If the element was successfully removed from the list.
  2. false - If the list is empty, or if index is greater than or equal to the list count.

Complexity

  • O(n)

_pop_back()

Removes the last element in the list (located at index count - 1). No shifts are required.

Declaration

FMOD bool PFX##_pop_back(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. true - If the element was successfully removed from the list.
  2. false - If the list is empty.

Complexity

  • O(1)

_push_if()

Adds an element at a given index if the condition evaluates to true.

Declaration

FMOD bool PFX##_push_if(SNAME *_list_, V element, size_t index, bool condition);

Parameters

  1. SNAME *_list_ - Target list.
  2. V element - Element to be added.
  3. size_t index - Index to add the new element.
    • Can't be greater than the list count.
  4. bool condition - Condition for the element to be added.

Returns

  1. true - If the element was successfully removed from the list.
  2. false - If the list is empty.

Complexity

  • O(n)

_pop_if()

Removes an element from a given index if the condition evaluates to true.

Declaration

FMOD bool PFX##_pop_if(SNAME *_list_, size_t index, bool condition);

Parameters

  1. SNAME *_list_ - Target list.
  2. size_t index - The index of the element to be removed.
    • Can't be greater than or equal to the list count.
  3. bool condition - Condition for the element to be removed.

Returns

  1. true - If the element was successfully removed from the list.
  2. false - If the list is empty.

Complexity

  • O(n)

_front()

Returns the first element (located at index 0) if the list is not empty.

Declaration

FMOD V PFX##_front(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. V - The first element in the list.
  2. 0 or NULL - If the list is empty.

Complexity

  • O(1)

_get()

Returns the element located at the given index if the list is not empty.

Declaration

FMOD V PFX##_get(SNAME *_list_, size_t index)

Parameters

  1. SNAME *_list_ - Target list.
  2. size_t index - Index to retrieve an element.
    • Can't be greater than or equal to the list count.

Returns

  1. V - The element in the list located at the given index.
  2. 0 or NULL - If the list is empty, or if index is greater than or equal to the list count.

Complexity

  • O(1)

_back()

Returns the last element (located at index count - 1) if the list is not empty.

Declaration

FMOD V PFX##_back(SNAME *_list_)

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. V - The last element in the list.
  2. 0 or NULL - If the list is empty.

Complexity

  • O(1)

_empty()

Returns true if the list is empty, otherwise false.

Declaration

FMOD bool PFX##_empty(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. true - If the list is empty.
  2. false - If there is at least one element in the list.

Complexity

  • O(1)

_full()

Returns true if the list is full, otherwise false. The list is considered full when its internal buffer is filled up, so the next element added to the list will required a resizing of the buffer, but note that the list has no limits to its capacity.

Declaration

FMOD bool PFX##_full(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. true - If the list internal buffer is full.
  2. false - If the list internal buffer is not full.

Complexity

  • O(1)

_count()

Returns the amount of elements in the list.

Declaration

FMOD size_t PFX##_count(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. size_t - The amount of elements in the list.

Complexity

  • O(1)

_capacity()

Returns the internal buffer's current capacity.

Declaration

FMOD size_t PFX##_capacity(SNAME *_list_);

Parameters

  1. SNAME *_list_ - Target list.

Returns

  1. size_t - The internal buffer's current capacity.

Complexity

  • O(1)

LinkedList

A list where each element is linked by nodes. Elements can be added and removed from both ends of the list and also in the middle. The linked list can be used to implement other data structures like queues, stacks and deques.

Stack

A LIFO/FILO structure backed by a growable array. All elements are added and removed from one end.

Queue

A FIFO/LILO structure backed by a circular buffer. Elements are added in one end and removed from the other.

Deque

A double-ended queue backed by a circular buffer. Elements can be added and removed from both ends but not in the middle. Can also be used as a queue.

Heap

A heap is a nearly complete binary tree backed by a growable array. The first element of the array (or the root element of the tree) is the highest/lowest element. The min-heap is commonly used as a priority-queue and a max-heap is commonly used to sort an array of elements.

TreeSet

A balanced binary tree that contains only unique elements to the set. Its elements are ordered.

TreeMap

A balanced binary tree that maps a key K to a value V. The difference from a hashmap is that its keys are ordered.

HashSet

A hashtable that contains only unique elements to the set. Its elements are not ordered.

HashMap

A hashtable that maps a key K to a value V.

Reference in new issue View Git Blame Copy Permalink