You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
140 lines
6.1 KiB
140 lines
6.1 KiB
/******************************************************************************
|
|
*
|
|
* Copyright 2016 Google, Inc.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at:
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*
|
|
******************************************************************************/
|
|
|
|
#pragma once
|
|
|
|
#include <stdbool.h>
|
|
#include <stdlib.h>
|
|
|
|
struct list_node_t;
|
|
typedef struct list_node_t list_node_t;
|
|
|
|
struct list_t;
|
|
typedef struct list_t list_t;
|
|
|
|
typedef void (*list_free_cb)(void* data);
|
|
|
|
// Iterator callback prototype used for |list_foreach|.
|
|
// |data| represents the list item currently being iterated, |context| is a
|
|
// user defined value passed into |list_foreach|.
|
|
// Callback must return true to continue iterating or false to stop iterating.
|
|
typedef bool (*list_iter_cb)(void* data, void* context);
|
|
|
|
// Returns a new, empty list. Returns NULL if not enough memory could be
|
|
// allocated for the list structure. The returned list must be freed with
|
|
// |list_free|. The |callback| specifies a function to be called whenever a
|
|
// list element is removed from the list. It can be used to release resources
|
|
// held by the list element, e.g. memory or file descriptor. |callback| may
|
|
// be NULL if no cleanup is necessary on element removal.
|
|
list_t* list_new(list_free_cb callback);
|
|
|
|
// Frees the list. This function accepts NULL as an argument, in which case it
|
|
// behaves like a no-op.
|
|
void list_free(list_t* list);
|
|
|
|
// Returns true if |list| is empty (has no elements), false otherwise.
|
|
// |list| may not be NULL.
|
|
bool list_is_empty(const list_t* list);
|
|
|
|
// Returns true if the list contains |data|, false otherwise.
|
|
// |list| may not be NULL.
|
|
bool list_contains(const list_t* list, const void* data);
|
|
|
|
// Returns the length of the |list|. |list| may not be NULL.
|
|
size_t list_length(const list_t* list);
|
|
|
|
// Returns the first element in the list without removing it. |list| may not
|
|
// be NULL or empty.
|
|
void* list_front(const list_t* list);
|
|
|
|
// Returns the last element in the list without removing it. |list| may not
|
|
// be NULL or empty.
|
|
void* list_back(const list_t* list);
|
|
|
|
// Returns the last node in the list without removing it. |list| may not
|
|
// be NULL or empty.
|
|
list_node_t* list_back_node(const list_t* list);
|
|
|
|
// Inserts |data| after |prev_node| in |list|. |data|, |list|, and |prev_node|
|
|
// may not be NULL. This function does not make a copy of |data| so the pointer
|
|
// must remain valid at least until the element is removed from the list or the
|
|
// list is freed. Returns true if |data| could be inserted, false otherwise
|
|
// (e.g. out of memory).
|
|
bool list_insert_after(list_t* list, list_node_t* prev_node, void* data);
|
|
|
|
// Inserts |data| at the beginning of |list|. Neither |data| nor |list| may be
|
|
// NULL.
|
|
// This function does not make a copy of |data| so the pointer must remain valid
|
|
// at least until the element is removed from the list or the list is freed.
|
|
// Returns true if |data| could be inserted, false otherwise (e.g. out of
|
|
// memory).
|
|
bool list_prepend(list_t* list, void* data);
|
|
|
|
// Inserts |data| at the end of |list|. Neither |data| nor |list| may be NULL.
|
|
// This function does not make a copy of |data| so the pointer must remain valid
|
|
// at least until the element is removed from the list or the list is freed.
|
|
// Returns true if |data| could be inserted, false otherwise (e.g. out of
|
|
// memory).
|
|
bool list_append(list_t* list, void* data);
|
|
|
|
// Removes |data| from the list. Neither |list| nor |data| may be NULL. If
|
|
// |data|
|
|
// is inserted multiple times in the list, this function will only remove the
|
|
// first instance. If a free function was specified in |list_new|, it will be
|
|
// called back with |data|. This function returns true if |data| was found in
|
|
// the list and removed, false otherwise.
|
|
bool list_remove(list_t* list, void* data);
|
|
|
|
// Removes all elements in the list. Calling this function will return the list
|
|
// to the
|
|
// same state it was in after |list_new|. |list| may not be NULL.
|
|
void list_clear(list_t* list);
|
|
|
|
// Iterates through the |list| and calls |callback| for each data element.
|
|
// Iteration continues until |callback| returns false. The function returns the
|
|
// pointer to last processed element, or NULL if the list is empty, or all calls
|
|
// to |callback| returned true. |context| is passed to |callback| on each
|
|
// iteration.
|
|
// If the list is empty, |callback| will never be called. It is safe to mutate
|
|
// the list inside the callback. If an element is added before the node being
|
|
// visited, there will be no callback for the newly-inserted node. Neither
|
|
// |list| nor |callback| may be NULL.
|
|
list_node_t* list_foreach(const list_t* list, list_iter_cb callback,
|
|
void* context);
|
|
|
|
// Returns an iterator to the first element in |list|. |list| may not be NULL.
|
|
// The returned iterator is valid as long as it does not equal the value
|
|
// returned by |list_end|.
|
|
list_node_t* list_begin(const list_t* list);
|
|
|
|
// Returns an iterator that points past the end of the list. In other words,
|
|
// this function returns the value of an invalid iterator for the given list.
|
|
// When an iterator has the same value as what's returned by this function, you
|
|
// may no longer call |list_next| with the iterator. |list| may not be NULL.
|
|
list_node_t* list_end(const list_t* list);
|
|
|
|
// Given a valid iterator |node|, this function returns the next value for the
|
|
// iterator. If the returned value equals the value returned by |list_end|, the
|
|
// iterator has reached the end of the list and may no longer be used for any
|
|
// purpose.
|
|
list_node_t* list_next(const list_node_t* node);
|
|
|
|
// Returns the value stored at the location pointed to by the iterator |node|.
|
|
// |node| must not equal the value returned by |list_end|.
|
|
void* list_node(const list_node_t* node);
|