list1.h File Reference
`#include <gwenhywfar/gwenhywfarapi.h>`
`#include <gwenhywfar/types.h>`
`#include <assert.h>`

Go to the source code of this file.

## Macros

#define | GWEN_DUMMY_EMPTY_ARG
#define | GWEN_LIST1_H
Typesafe Macros
#define | GWEN_LIST_ELEMENT(t)
#define | GWEN_LIST_FINI(t, element)
#define | GWEN_LIST_FUNCTION_DEFS(t, pr)
#define | GWEN_LIST_FUNCTION_DEFS_CONST(t, pr)
#define | GWEN_LIST_FUNCTION_DEFS_NOCONST(t, pr)
#define | GWEN_LIST_FUNCTION_LIB_DEFS(t, pr, decl)
#define | GWEN_LIST_FUNCTION_LIB_DEFS_CONST(t, pr, decl)
#define | GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl)
#define | GWEN_LIST_FUNCTIONS(t, pr)
#define | GWEN_LIST_INIT(t, element)

## Internal Functions

All functions and structs within this group should be considered internal. They just implement the functionality behind the typesafe list macros (see GWEN_LIST_FUNCTION_LIB_DEFS and following).
typedef struct GWEN_LIST1 | GWEN_LIST1
GWENHYWFAR_API int | GWEN_List1_Add (GWEN_LIST1 *l, GWEN_LIST1_ELEMENT *el)
GWENHYWFAR_API int | GWEN_List1_AddList (GWEN_LIST1 *dest, GWEN_LIST1 *l)
GWENHYWFAR_API int | GWEN_List1_Del (GWEN_LIST1_ELEMENT *el)
typedef struct GWEN_LIST1_ELEMENT | GWEN_LIST1_ELEMENT
GWENHYWFAR_API void | GWEN_List1_free (GWEN_LIST1 *l)
GWENHYWFAR_API int | GWEN_List1_GetCount (const GWEN_LIST1 *l)
GWENHYWFAR_API void * | GWEN_List1_GetFirst (const GWEN_LIST1 *l)
GWENHYWFAR_API void * | GWEN_List1_GetLast (const GWEN_LIST1 *l)
GWENHYWFAR_API int | GWEN_List1_Insert (GWEN_LIST1 *l, GWEN_LIST1_ELEMENT *el)
GWENHYWFAR_API GWEN_LIST1 * | GWEN_List1_new (void)
GWENHYWFAR_API GWEN_LIST1_SORT_FN | GWEN_List1_SetSortFn (GWEN_LIST1 *l, GWEN_LIST1_SORT_FN fn)
GWENHYWFAR_API void | GWEN_List1_Sort (GWEN_LIST1 *l, int ascending)
typedef int GWENHYWFAR_CB(* | GWEN_LIST1_SORT_FN) (const void *a, const void *b, int ascending)
GWENHYWFAR_API void | GWEN_List1Element_free (GWEN_LIST1_ELEMENT *el)
GWENHYWFAR_API void * | GWEN_List1Element_GetData (const GWEN_LIST1_ELEMENT *el)
GWENHYWFAR_API void * | GWEN_List1Element_GetNext (const GWEN_LIST1_ELEMENT *el)
GWENHYWFAR_API void * | GWEN_List1Element_GetPrevious (const GWEN_LIST1_ELEMENT *el)
GWENHYWFAR_API GWEN_LIST1_ELEMENT * | GWEN_List1Element_new (void *d)

## Macro Definition Documentation

## GWEN_DUMMY_EMPTY_ARG

#define GWEN_DUMMY_EMPTY_ARG

Necessary for MSVC compiler because it does not accept a left-out macro argument.

Definition at line 34 of file list1.h.

## GWEN_LIST1_H

#define GWEN_LIST1_H

Definition at line 39 of file list1.h.

## GWEN_LIST_ELEMENT

#define GWEN_LIST_ELEMENT | ( |  | t | ) |

Value:
GWEN_LIST1_ELEMENT *_list1_element;
GWEN_LIST1_ELEMENT
struct GWEN_LIST1_ELEMENT GWEN_LIST1_ELEMENT
Definition list1.h:156

Use this inside the declaration of a struct for which you want to create lists.

Definition at line 255 of file list1.h.

## GWEN_LIST_FINI

#define GWEN_LIST_FINI | ( |  | t,
|  |  | element )

Value:
if (element && element->_list1_element) { \
GWEN_List1Element_free(element->_list1_element); \
element->_list1_element=0; \
}

Use this in your code file (*.c) inside the fini code for the struct you want to use in lists (in GWEN these are the functions which end with "_free".

Definition at line 475 of file list1.h.

## GWEN_LIST_FUNCTION_DEFS

#define GWEN_LIST_FUNCTION_DEFS | ( |  | t,
|  |  | pr )

Value:
GWEN_LIST_FUNCTION_LIB_DEFS(t, pr, GWEN_DUMMY_EMPTY_ARG)
GWEN_DUMMY_EMPTY_ARG
#define GWEN_DUMMY_EMPTY_ARG
Definition idmap.h:60
GWEN_LIST_FUNCTION_LIB_DEFS
#define GWEN_LIST_FUNCTION_LIB_DEFS(t, pr, decl)
Definition list1.h:349

This macro should be used in applications, not in libraries. In libraries please use the macro GWEN_LIST_FUNCTION_LIB_DEFS.

Definition at line 358 of file list1.h.

## GWEN_LIST_FUNCTION_DEFS_CONST

#define GWEN_LIST_FUNCTION_DEFS_CONST | ( |  | t,
|  |  | pr )

Value:
GWEN_LIST_FUNCTION_LIB_DEFS_CONST(t, pr, GWEN_DUMMY_EMPTY_ARG)
GWEN_LIST_FUNCTION_LIB_DEFS_CONST
#define GWEN_LIST_FUNCTION_LIB_DEFS_CONST(t, pr, decl)
Definition list1.h:264

Definition at line 294 of file list1.h.

## GWEN_LIST_FUNCTION_DEFS_NOCONST

#define GWEN_LIST_FUNCTION_DEFS_NOCONST | ( |  | t,
|  |  | pr )

Value:
GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST(t, pr, GWEN_DUMMY_EMPTY_ARG)
GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST
#define GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl)
Definition list1.h:282

Definition at line 297 of file list1.h.

## GWEN_LIST_FUNCTION_LIB_DEFS

#define GWEN_LIST_FUNCTION_LIB_DEFS | ( |  | t,
|  |  | pr,
|  |  | decl )

Value:
GWEN_LIST_FUNCTION_LIB_DEFS_CONST(t, pr, decl) \
GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl)

Use this in public header files to define some prototypes for list functions. Let's assume the type of your list elements is "MYTYPE" and you want to use the prefix "MyType_" for the list functions. The following function prototypes will then be created:

- void MyType_List_Add(MYTYPE *element, MYTYPE_LIST *list);
  Adds (appends) a MYTYPE struct at the end of the given list. (We apologize for the unusual argument order here.)
- void MyType_List_Del(MYTYPE *element);
  Removes a MyType struct from the list it is enlisted to.
- MYTYPE *MyType_List_First(MYTYPE *element);
  Returns the first element of the given list.
- MYTYPE* MyType_List_Next(const MYTYPE *element);
  Returns the next list element to the given one (the successor) in its list.
- MYTYPE* MyType_List_Previous(const MYTYPE *element);
  Returns the previous list element to the given one (the predecessor) in its list.
- void MyType_List_Clear(MYTYPE *element);
  Frees all entries of the given list. This function assumes that there is a function Mytype_free().
- MYTYPE_LIST *MyType_List_new();
  Creates a new list of elements of MYTYPE type.
- void MyType_List_free(MYTYPE_LIST *l);
  Clears and frees a list of elements of MYTYPE type. All objects inside the list are freed. This function assumes that there is a function Mytype_free().

Definition at line 349 of file list1.h.

## GWEN_LIST_FUNCTION_LIB_DEFS_CONST

#define GWEN_LIST_FUNCTION_LIB_DEFS_CONST | ( |  | t,
|  |  | pr,
|  |  | decl )

Value:
/*typedef GWEN_LIST1 t##_LIST;*/ \
typedef struct t##_LIST t##_LIST; \
typedef int GWENHYWFAR_CB (*t##_LIST_SORT_FN)(const t *a, const t *b, int ascending); \
typedef t* (t##_LIST_FOREACH)(t *element, void *user_data); \
\
\
decl t* pr##_List_First(const t##_LIST *l); \
decl t* pr##_List_Last(const t##_LIST *l); \
decl t* pr##_List_Next(const t *element); \
decl t* pr##_List_Previous(const t *element); \
decl uint32_t pr##_List_GetCount(const t##_LIST *l); \
decl int pr##_List_HasElement(const t##_LIST *l, const t *element); \
decl t##_LIST_SORT_FN pr##_List_SetSortFn(t##_LIST *l, t##_LIST_SORT_FN fn); \
decl void pr##_List_Sort(t##_LIST *l, int ascending); \
decl t* pr##_List_ForEach(t##_LIST *l, t##_LIST_FOREACH fn, void *user_data);
GWENHYWFAR_CB
#define GWENHYWFAR_CB
Definition gwenhywfarapi.h:89

Use this macro in your public header files to export only list functions which do not modify a list. This allows your code to return lists which can not be modified by callers. It also prevents callers from creating their own lists (this is sometimes needed).

Definition at line 264 of file list1.h.

## GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST

#define GWEN_LIST_FUNCTION_LIB_DEFS_NOCONST | ( |  | t,
|  |  | pr,
|  |  | decl )

Value:
typedef GWEN_LIST1_ELEMENT t##_LIST_ELEMENT; \
\
decl void pr##_List_Clear(t##_LIST *l); \
decl t##_LIST* pr##_List_new(); \
decl void pr##_List_free(t##_LIST *l); \
decl int pr##_List_AddList(t##_LIST *dst, t##_LIST *l); \
decl int pr##_List_Add(t *element, t##_LIST *list); \
decl int pr##_List_Insert(t *element, t##_LIST *list); \
decl int pr##_List_Del(t *element);

Definition at line 282 of file list1.h.

## GWEN_LIST_FUNCTIONS

#define GWEN_LIST_FUNCTIONS | ( |  | t,
|  |  | pr )

Use this inside your code files (*.c). Actually implements the functions for which the prototypes have been defined via GWEN_LIST_FUNCTION_DEFS.

Definition at line 367 of file list1.h.

## GWEN_LIST_INIT

#define GWEN_LIST_INIT | ( |  | t,
|  |  | element )

Value:
element->_list1_element=GWEN_List1Element_new(element);
GWEN_List1Element_new
GWENHYWFAR_API GWEN_LIST1_ELEMENT * GWEN_List1Element_new(void *d)

Use this in your code file (*.c) inside the init code for the struct you want to use in lists (in GWEN these are the functions which end with "_new".

Definition at line 466 of file list1.h.

## Typedef Documentation

## GWEN_LIST1

typedef struct GWEN_LIST1 GWEN_LIST1

Definition at line 155 of file list1.h.

## GWEN_LIST1_ELEMENT

typedef struct GWEN_LIST1_ELEMENT GWEN_LIST1_ELEMENT

Definition at line 156 of file list1.h.

## GWEN_LIST1_SORT_FN

typedef int GWENHYWFAR_CB(* GWEN_LIST1_SORT_FN) (const void *a, const void *b, int ascending)

Definition at line 158 of file list1.h.

## Function Documentation

## GWEN_List1_Add()

GWENHYWFAR_API int GWEN_List1_Add | ( | GWEN_LIST1 * | l,
|  | GWEN_LIST1_ELEMENT * | el )

Adds (appends) a list element at the end of the list. (This operation is also called "append" or "push_back" elsewhere.)

References GWENHYWFAR_API.

## GWEN_List1_AddList()

GWENHYWFAR_API int GWEN_List1_AddList | ( | GWEN_LIST1 * | dest,
|  | GWEN_LIST1 * | l )

Adds (appends) the second list to the end of the first list. (This operation is also called "append" or "concatenate" elsewhere.)

References GWENHYWFAR_API.

## GWEN_List1_Del()

GWENHYWFAR_API int GWEN_List1_Del | ( | GWEN_LIST1_ELEMENT * | el | ) |

Deletes (removes) a list element from the list it used to belong to. The list element is not free'd or anything, it is only removed from the list it used to belong to. (This operation is also called "remove" or "unlink" elsewhere.)

References GWENHYWFAR_API.

## GWEN_List1_free()

GWENHYWFAR_API void GWEN_List1_free | ( | GWEN_LIST1 * | l | ) |

Free (delete) an existing list. The list elements are untouched by this function; they need to be freed beforehand.

References GWENHYWFAR_API.

## GWEN_List1_GetCount()

GWENHYWFAR_API int GWEN_List1_GetCount | ( | const GWEN_LIST1 * | l | ) |

Returns the number of elements in this list. This value is cached in the list structure, so this function is a cheap function.

References GWENHYWFAR_API.

## GWEN_List1_GetFirst()

GWENHYWFAR_API void * GWEN_List1_GetFirst | ( | const GWEN_LIST1 * | l | ) |

Returns the data pointer of the first list element.

References GWENHYWFAR_API.

## GWEN_List1_GetLast()

GWENHYWFAR_API void * GWEN_List1_GetLast | ( | const GWEN_LIST1 * | l | ) |

Returns the data pointer of the last list element.

References GWENHYWFAR_API.

## GWEN_List1_Insert()

GWENHYWFAR_API int GWEN_List1_Insert | ( | GWEN_LIST1 * | l,
|  | GWEN_LIST1_ELEMENT * | el )

Inserts (prepends) a list element at the beginning of the list. (This operation is also called "prepend" or "push_front" elsewhere.)

References GWENHYWFAR_API.

## GWEN_List1_new()

GWENHYWFAR_API GWEN_LIST1 * GWEN_List1_new | ( | void |  | ) |

Allocate (create) a new empty list.

References GWENHYWFAR_API.

## GWEN_List1_SetSortFn()

GWENHYWFAR_API GWEN_LIST1_SORT_FN GWEN_List1_SetSortFn | ( | GWEN_LIST1 * | l,
|  | GWEN_LIST1_SORT_FN | fn )

References GWENHYWFAR_API.

## GWEN_List1_Sort()

GWENHYWFAR_API void GWEN_List1_Sort | ( | GWEN_LIST1 * | l,
|  | int | ascending )

References GWENHYWFAR_API.

## GWEN_List1Element_free()

GWENHYWFAR_API void GWEN_List1Element_free | ( | GWEN_LIST1_ELEMENT * | el | ) |

Free (delete) a list element structure.

References GWENHYWFAR_API.

## GWEN_List1Element_GetData()

GWENHYWFAR_API void * GWEN_List1Element_GetData | ( | const GWEN_LIST1_ELEMENT * | el | ) |

Returns the data pointer of the given list element structure.

References GWENHYWFAR_API.

## GWEN_List1Element_GetNext()

GWENHYWFAR_API void * GWEN_List1Element_GetNext | ( | const GWEN_LIST1_ELEMENT * | el | ) |

Returns the data pointer of the list element that is the next one (successor) to the given one in its list. If there is no such prepending list element, returns NULL.

## GWEN_List1Element_GetPrevious()

GWENHYWFAR_API void * GWEN_List1Element_GetPrevious | ( | const GWEN_LIST1_ELEMENT * | el | ) |

Returns the data pointer of the list element that is the previous (predecessor) to the given one in its list. If there is no such prepending list element, returns NULL.

References GWENHYWFAR_API.

## GWEN_List1Element_new()

GWENHYWFAR_API GWEN_LIST1_ELEMENT * GWEN_List1Element_new | ( | void * | d | ) |

Allocate (create) a new list element structure.

References GWENHYWFAR_API.