queue.h File Reference

Interface for the abstract data type (ADT) queue. More...

#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

Typedefs
typedef struct queue	Queue

Functions
Queue *	Queue_create (size_t elem_sz)
	Creates an empty, heap-allocated queue.
void	Queue_destroy (Queue *queue)
	Destroys a heap-allocated queue.
size_t	Queue_capacity (Queue *queue)
	Queries the capacity of a queue.
bool	Queue_empty (Queue *queue)
	Determines whether a queue is empty.
size_t	Queue_size (Queue *queue)
	Queries the size of a queue.
bool	Queue_front (Queue *queue, void *elem)
	Accesses the front element of a queue.
bool	Queue_enqueue (Queue *queue, void const *elem)
	Adds an element to the end of a queue.
bool	Queue_dequeue (Queue *queue)
	Removes the front element from a queue.
void	Queue_print (Queue *queue, char const *sep, bool vertical, void(*print_element)(void const *))
	Prints a string representation of the elements in a queue to the standard output.

Detailed Description

Interface for the abstract data type (ADT) queue.

Author

KriztoferY (https://github.com/KriztoferY)

Version

0.1.0

Copyright

Copyright (c) 2022 KriztoferY. All rights reserved.

Queue is a sequential ADT that emulates the first-in-first-out behavior of a queue in real world. This module define the interface of the Queue ADT.

Use Queue_create() to create a queue, which should be destroyed when it is no longer needed using Queue_destroy(). To add an element at the end of a queue, use Queue_enqueue(). To remove the front element, i.e, the least recently added element, from a queue, use Queue_dequeue().

All functions that accept a pointer to a queue asserts at compile time that the queue is not NULL. That is, such assertion can be disabled by adding the -DNDEBUG flag when compiling the library and/or programs using gcc.

Typedef Documentation

Queue

typedef struct queue Queue

An opaque type representing a generic queue.

Function Documentation

Queue_capacity()

size_t Queue_capacity

(

Queue *

queue

)

Queries the capacity of a queue.

For node-based implementations, it always return ULONG_MAX to suggest that the queue can hold as many elements as system memory allows.

Parameters

[in]

queue

The queue to query.

Returns

Maximum number of elements that can be stored by the queue.

Queue_create()

Queue * Queue_create

(

size_t

elem_sz

)

Creates an empty, heap-allocated queue.

It's the caller's responsibility to

1. call Queue_destroy() to free all allocated memory associated with the queue created; and
2. ensure elem_sz is a proper positive integer.

Parameters

[in]

elem_sz

Size of each queue elements in bytes.

Returns

The queue created on success, NULL otherwise.

Queue_dequeue()

bool Queue_dequeue

(

Queue *

queue

)

Removes the front element from a queue.

Parameters

[in]

queue

The queue from which its least recent element is to remove.

Returns

false if the queue is empty, true otherwise (on success).

Queue_destroy()

void Queue_destroy

(

Queue *

queue

)

Destroys a heap-allocated queue.

It is a no-op if the queue is NULL.

Parameters

queue

The queue to destroy.

Queue_empty()

bool Queue_empty

(

Queue *

queue

)

Determines whether a queue is empty.

Parameters

[in]

queue

The queue to query.

Returns

true if the queue is empty, false otherwise.

Queue_enqueue()

bool Queue_enqueue	(	Queue *	queue,
		void const *	elem
	)

Adds an element to the end of a queue.

Parameters

[in]	queue	The queue to which the element is to add.
[in]	elem	The element to add.

Returns

false if the system cannot allocate sufficient memory to complete the operation; true otherwise (on success).

Queue_front()

bool Queue_front	(	Queue *	queue,
		void *	elem
	)

Accesses the front element of a queue.

Parameters

[in]	queue	The query to query.
[out]	elem	The front element if the queue is not empty, undefined otherwise.

Returns

false if the queue is empty, true otherwise (on success).

Queue_print()

void Queue_print	(	Queue *	queue,
		char const *	sep,
		bool	vertical,
		void(*)(void const *)	print_element
	)

Prints a string representation of the elements in a queue to the standard output.

Elements are listed in queue order from left to right in a horizontal layout, or from top to bottom in a vertical layout.

Parameters

[in]	queue	The queue of which the elements to print. It's a no-op if queue is NULL.
[in]	sep	A string used to separate successive elements. Has no effect if vertical is true. Defaults to ",".
[in]	vertical	Elements are listed vertically if true, horizontally otherwise.
[in]	print_element	A function to use for printing a queue element.

Queue_size()

size_t Queue_size

(

Queue *

queue

)

Queries the size of a queue.

Parameters

[in]

queue

The queue to query.

Returns

Number of elements in the queue.