g2l.h File Reference

#include <stdbool.h>
#include <sys/types.h>

Go to the source code of this file.

Typedefs
typedef struct g2l_t	g2l_t

Functions
g2l_t *	g2l_create (size_t data_size, bool abort_on_enomem)
void	g2l_clear (g2l_t *self)
void	g2l_destroy (g2l_t *self)
size_t	g2l_size (g2l_t const *self)
int	g2l_push (g2l_t *self, void const *data)
bool	g2l_pop (g2l_t *self, void *data)
bool	g2l_shift (g2l_t *self, void *data)
bool	g2l_enqueue (g2l_t *self, void const *data)
bool	g2l_dequeue (g2l_t *self, void *data)

Typedef Documentation

g2l_t

typedef struct g2l_t g2l_t

An opaque data type used as a container for the generic doubly linked list implementation, and which must be instantiated using the g2l_create function.

See also

g2l_create, g2l_destroy

Example:

/*
    Copyright (c) 2024 BB-301 <fw3dg3@gmail.com> [Official repository](https://github.com/BB-301/c-generic-doubly-linked-list)
 
    Permission is hereby granted, free of charge, to any person
    obtaining a copy of this software and associated documentation
    files (the “Software”), to deal in the Software without restriction,
    including without limitation the rights to use, copy, modify, merge,
    publish, distribute, sublicense, and/or sell copies of the Software,
    and to permit persons to whom the Software is furnished to do so,
    subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
*/
 
/*
    ======================
    Example: Quick example
    ======================
 
    This is a quick "getting started" example used to illustrate
    the basic structure of a program that uses lib<g2l>. This example
    is featured in the [repository](https://github.com/BB-301/c-generic-doubly-linked-list)'s
    README.md file.
 
    Here, the `g2l_t` type is used to implement both a stack and a queue.
    The stack's data type is a `char`, while the queue's data type is
    an application defined structure (named `struct my_data_type`) containing
    two `int` members; namely, `value_1` and `value_2`.
*/
 
#include <stdio.h>
#include <stdlib.h>
 
#include "g2l.h"
 
#define NUMBER_OF_ITEMS (4)
#define DIVIDER "---------------------------------"
 
struct my_data_type
{
    int value_1;
    int value_2;
};
 
static void demo_char_data_type(void);
static void demo_custom_data_type(void);
 
int main(void)
{
    demo_char_data_type();
    demo_custom_data_type();
    fprintf(stdout, "\n");
 
    return 0;
}
 
static void demo_char_data_type(void)
{
    fprintf(stdout, "\n%s\nDEMO: stack with 'char' data type\n%s\n\n", DIVIDER, DIVIDER);
 
    char tmp;
    g2l_t *stack = g2l_create(sizeof(char), true);
 
    tmp = 'a';
    for (int i = 0; i < NUMBER_OF_ITEMS; i++)
    {
        g2l_push(stack, &tmp);
        fprintf(stdout, "pushed: %c [n = %zu]\n", tmp, g2l_size(stack));
        tmp += 1;
    }
    fprintf(stdout, "\n");
 
    while (g2l_size(stack) > 0)
    {
        g2l_pop(stack, &tmp);
        fprintf(stdout, "popped: %c [n = %zu]\n", tmp, g2l_size(stack));
    }
 
    g2l_destroy(stack);
}
 
static void demo_custom_data_type(void)
{
    fprintf(stdout, "\n%s\nDEMO: queue with custom data type\n%s\n\n", DIVIDER, DIVIDER);
 
    struct my_data_type tmp;
    g2l_t *queue = g2l_create(sizeof(struct my_data_type), true);
 
    for (int i = 0; i < NUMBER_OF_ITEMS; i++)
    {
        tmp.value_1 = i + i;
        tmp.value_2 = i * i;
        // NOTE: `g2l_enqueue` is simply an alias for `g2l_push`
        g2l_enqueue(queue, &tmp);
        fprintf(
            stdout,
            "enqueued: struct { .value_1 = %i, .value_2 = %i } [n = %zu]\n",
            tmp.value_1, tmp.value_2, g2l_size(queue));
    }
    fprintf(stdout, "\n");
 
    while (g2l_size(queue) > 0)
    {
        // NOTE: `g2l_dequeue` is simply an alias for `g2l_shift`
        g2l_dequeue(queue, &tmp);
        fprintf(
            stdout,
            "dequeued: struct { .value_1 = %i, .value_2 = %i } [n = %zu]\n",
            tmp.value_1, tmp.value_2, g2l_size(queue));
    }
 
    g2l_destroy(queue);
}

Function Documentation

g2l_clear()

void g2l_clear

(

g2l_t *

self

)

A function that can be used to clear (i.e., empty) a linked list object.

Parameters

self	A pointer to the g2l_t instance to be cleared.

g2l_create()

g2l_t * g2l_create	(	size_t	data_size,
		bool	abort_on_enomem
	)

The function that must be used to instantiate a new linked list object (i.e., g2l_t ).

Parameters

data_size	The size, in bytes, of the data type that will be stored in the created instance.
abort_on_enomem	Whether ENOMEM errors should result in the process being aborted (true) or whether the function should simply return the NULL pointer and let the application deal with the error.

Returns

g2l_t* A pointer to the created linked list object.

Note

- If abort_on_enomem is set to false and an error occurs, that error will be due to an internal call to malloc failing, in which case errno will contain ENOMEM , which will have been set by malloc .

- Setting abort_on_enomem to false will also require the application to inspect the value returned by g2l_push (and its g2l_enqueue alias), which function also internally makes use of malloc , and which could consequently obtain ENOMEM .

See also

g2l_destroy

g2l_dequeue()

bool g2l_dequeue	(	g2l_t *	self,
		void *	data
	)

An alias to g2l_shift , this function can be used to "dequeue" (i.e., shift) the list's oldest element (and optionally retrieve the value contained in that element).

Parameters

self	A pointer to the g2l_t instance for which to remove the oldest element.
data	A pointer to memory into which the list's oldest element's data should be copied before the element is freed. The NULL pointer can be passed if the data is not needed by the application.

Returns

bool A boolean value indicating whether the operation was successful (i.e, whether a value was removed). A false value simply means that the list was already empty at the moment when the operation was performed, else the value will be true.

Note

- The g2l_dequeue function is an alias for g2l_shift .

See also

g2l_shift

g2l_destroy()

void g2l_destroy

(

g2l_t *

self

)

The function that should be used to destroy a linked list object once it is no longer needed by the application.

Parameters

self	A pointer to the g2l_t instance to be destroyed.

See also

g2l_create

g2l_enqueue()

bool g2l_enqueue	(	g2l_t *	self,
		void const *	data
	)

An alias to g2l_push , a function that can be used to "enqueue" a new element to the linked list object self .

Parameters

self	A pointer to the g2l_t instance into which to enqueue (i.e., push) the new element.
data	A pointer to arbitrary memory of size defined when instantiating the object using g2l_create , which is to be copied and stored inside the linked list object self .

Returns

int An integer value that will be 0 if the new element was successfully added, else it will be ENOMEM .

Note

- See the documentation for g2l_push for a discussion about the possible returned values.

- The g2l_enqueue function is an alias for g2l_push .

See also

g2l_push

g2l_pop()

bool g2l_pop	(	g2l_t *	self,
		void *	data
	)

The function that must be used to "pop" the stack (and optionally retrieve the value contained in the list's top-most (i.e., youngest) element).

Parameters

self	A pointer to the g2l_t instance for which to remove the top-most (i.e., youngest) element.
data	A pointer to memory into which the list's top-most element's data should be copied before the element is freed. The NULL pointer can be passed if the data is not needed by the application.

Returns

bool A boolean value indicating whether the operation was successful (i.e, whether a value was popped). A false value simply means that the list was already empty at the moment when the operation was performed, else the value will be true.

g2l_push()

int g2l_push	(	g2l_t *	self,
		void const *	data
	)

The function that must be used to add a new element to the linked list object self .

Parameters

self	A pointer to the g2l_t instance into which to push the new element.
data	A pointer to arbitrary memory of size defined when instantiating the object using g2l_create , which is to be copied and stored inside the linked list object self .

Returns

int An integer value that will be 0 if the new element was successfully added, else it will be ENOMEM .

Note

- If self has been instantiated with g2l_create 's abort_on_enomem argument set to true, then this function will always return 0, because possible ENOMEM errors obtained using malloc will result in the process being aborted. Therefore, in such cases (i.e., when setting abort_on_enomem = true), the output of the g2l_push should simply be ignored.

- The g2l_enqueue function is an alias for g2l_push .

See also

g2l_enqueue

g2l_shift()

bool g2l_shift	(	g2l_t *	self,
		void *	data
	)

The function that must be used to "shift" the list's oldest element (and optionally retrieve the value contained in that element).

Parameters

self	A pointer to the g2l_t instance for which to remove the oldest element.
data	A pointer to memory into which the list's oldest element's data should be copied before the element is freed. The NULL pointer can be passed if the data is not needed by the application.

Returns

bool A boolean value indicating whether the operation was successful (i.e, whether a value was shifted). A false value simply means that the list was already empty at the moment when the operation was performed, else the value will be true.

Note

- The g2l_dequeue function is an alias for g2l_shift .

See also

g2l_dequeue

g2l_size()

size_t g2l_size

(

g2l_t const *

self

)

A function that can be used to retrieve the current number of items contained in the linked list object self .

Parameters

self	A pointer to the g2l_t object for which to retrieve the number of internal elements.

Returns

size_t The number of elements in the self linked list object.