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_TREE_FUNCTION_LIB_DEFS and following). | |
typedef struct GWEN_TREE | GWEN_TREE |
typedef struct GWEN_TREE_ELEMENT | GWEN_TREE_ELEMENT |
GWENHYWFAR_API void | GWEN_Tree_Add (GWEN_TREE *l, GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void | GWEN_Tree_AddChild (GWEN_TREE_ELEMENT *where, GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void | GWEN_Tree_AddList (GWEN_TREE *dest, GWEN_TREE *l) |
GWENHYWFAR_API void | GWEN_Tree_Del (GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void | GWEN_Tree_free (GWEN_TREE *l) |
GWENHYWFAR_API int | GWEN_Tree_GetCount (const GWEN_TREE *l) |
GWENHYWFAR_API void * | GWEN_Tree_GetFirst (const GWEN_TREE *l) |
GWENHYWFAR_API void * | GWEN_Tree_GetLast (const GWEN_TREE *l) |
GWENHYWFAR_API void | GWEN_Tree_Insert (GWEN_TREE *l, GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void | GWEN_Tree_InsertChild (GWEN_TREE_ELEMENT *where, GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API GWEN_TREE * | GWEN_Tree_new () |
GWENHYWFAR_API void | GWEN_TreeElement_free (GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void * | GWEN_TreeElement_GetBelow (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API uint32_t | GWEN_TreeElement_GetChildrenCount (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void * | GWEN_TreeElement_GetFirstChild (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void * | GWEN_TreeElement_GetLastChild (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void * | GWEN_TreeElement_GetNext (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void * | GWEN_TreeElement_GetParent (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API void * | GWEN_TreeElement_GetPrevious (const GWEN_TREE_ELEMENT *el) |
GWENHYWFAR_API GWEN_TREE_ELEMENT * | GWEN_TreeElement_new (void *d) |
Typesafe Macros | |
#define | GWEN_TREE_ELEMENT(t) GWEN_TREE_ELEMENT *_tree_element; |
#define | GWEN_TREE_FINI(t, element) |
#define | GWEN_TREE_FUNCTION_DEFS(t, pr) GWEN_TREE_FUNCTION_LIB_DEFS(t, pr, GWEN_DUMMY_EMPTY_ARG) |
#define | GWEN_TREE_FUNCTION_DEFS_CONST(t, pr) GWEN_TREE_FUNCTION_LIB_DEFS_CONST(t, pr, GWEN_DUMMY_EMPTY_ARG) |
#define | GWEN_TREE_FUNCTION_DEFS_NOCONST(t, pr) GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST(t, pr, GWEN_DUMMY_EMPTY_ARG) |
#define | GWEN_TREE_FUNCTION_LIB_DEFS(t, pr, decl) |
#define | GWEN_TREE_FUNCTION_LIB_DEFS_CONST(t, pr, decl) |
#define | GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl) |
#define | GWEN_TREE_FUNCTIONS(t, pr) |
#define | GWEN_TREE_INIT(t, element) element->_tree_element=GWEN_TreeElement_new(element); |
The macros of this group facilitates typesafe use of trees.
Let's assume you have a structure type called MYSTRUCT and you want to manage lists of them. Let's further assume that you want the functions dealing with that struct have prefixes like MyStruct (as in MyStruct_new) The header file would look like this:
/ * mystruct.h * / #ifndef MYSTRUCT_H #define MYSTRUCT_H typedef struct MYSTRUCT MYSTRUCT; GWEN_TREE_FUNCTION_DEFS(MYSTRUCT, MyStruct); struct MYSTRUCT { GWEN_TREE_ELEMENT(MYSTRUCT); int myData; } MYSTRUCT *MyStruct_new(int myData); void MyStruct_free(MYSTRUCT *myStruct); #endif
This defines all necessary data and function prototypes needed for list management.
The code file would look quite similar to the following:
/ * mystruct.c * / GWEN_TREE_FUNCTIONS(MYSTRUCT, MyStruct) MYSTRUCT *MyStruct_new(int myData) { MYSTRUCT *pMyStruct; pMyStruct=(MYSTRUCT*)malloc(sizeof(MYSTRUCT)); memset(pMyStruct, 0, sizeof(MYSTRUCT)); GWEN_TREE_INIT(MYSTRUCT, pMyStruct) pMyStruct->myData=myData; return pMyStruct; } void MyStruct_free(MYSTRUCT *pMyStruct) { if (pMyStruct) { pMyStruct->myData=0; GWEN_TREE_FINI(MYSTRUCT, pMyStruct) free(pMyStruct); } }
Note: When writing these macro code lines, the original ISO C89 standard for the C language does not allow terminating the macro statement with a semicolon ';'. Any recent compiler will probably silently ignore such an extra ';', but you should be aware that this can cause problems once one of your users tries to compile this with a different compiler. Therefore these code lines should end directly with the closing parentheses.
The list management code assumes that there is a function called (in this example) MyStruct_free() (or generally: TYPEPREFIX_free). This is used when destroying a list of MYSTRUCT elements. In this case all elements still enlisted are destroyed upon destruction of the list.
#define GWEN_TREE_ELEMENT | ( | t | ) | GWEN_TREE_ELEMENT *_tree_element; |
Use this inside the declaration of a struct for which you want to create lists.
Definition at line 276 of file tree.h.
Referenced by GWEN_Tree_AddList(), and GWEN_TreeElement_new().
#define GWEN_TREE_FINI | ( | t, | |||
element | ) |
Value:
if (element && element->_tree_element) { \ GWEN_TreeElement_free(element->_tree_element); \ element->_tree_element=0; \ }
#define GWEN_TREE_FUNCTION_DEFS | ( | t, | |||
pr | ) | GWEN_TREE_FUNCTION_LIB_DEFS(t, pr, GWEN_DUMMY_EMPTY_ARG) |
This macro should be used in applications, not in libraries. In libraries please use the macro GWEN_TREE_FUNCTION_LIB_DEFS.
#define GWEN_TREE_FUNCTION_DEFS_CONST | ( | t, | |||
pr | ) | GWEN_TREE_FUNCTION_LIB_DEFS_CONST(t, pr, GWEN_DUMMY_EMPTY_ARG) |
#define GWEN_TREE_FUNCTION_DEFS_NOCONST | ( | t, | |||
pr | ) | GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST(t, pr, GWEN_DUMMY_EMPTY_ARG) |
#define GWEN_TREE_FUNCTION_LIB_DEFS | ( | t, | |||
pr, | |||||
decl | ) |
Value:
GWEN_TREE_FUNCTION_LIB_DEFS_CONST(t, pr, decl) \ GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl)
#define GWEN_TREE_FUNCTION_LIB_DEFS_CONST | ( | t, | |||
pr, | |||||
decl | ) |
Value:
typedef GWEN_TREE t##_TREE; \ \ decl t* pr##_Tree_GetFirst(const t##_TREE *l); \ decl t* pr##_Tree_GetLast(const t##_TREE *l); \ decl t* pr##_Tree_GetNext(const t *element); \ decl t* pr##_Tree_GetPrevious(const t *element); \ decl t* pr##_Tree_GetBelow(const t *element); \ decl uint32_t pr##_Tree_GetCount(const t##_TREE *l); \ decl int pr##_Tree_HasElement(const t##_TREE *l, const t *element); \ decl t* pr##_Tree_GetFirstChild(const t *element); \ decl t* pr##_Tree_GetLastChild(const t *element); \ decl uint32_t pr##_Tree_GetChildrenCount(const t *element); \ decl t* pr##_Tree_GetParent(const t *element);
#define GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST | ( | t, | |||
pr, | |||||
decl | ) |
Value:
typedef GWEN_TREE_ELEMENT t##_TREE_ELEMENT; \ \ decl void pr##_Tree_Clear(t##_TREE *l); \ decl t##_TREE* pr##_Tree_new(); \ decl void pr##_Tree_free(t##_TREE *l); \ decl void pr##_Tree_AddList(t##_TREE *dst, t##_TREE *l); \ decl void pr##_Tree_Add(t##_TREE *list, t *element); \ decl void pr##_Tree_Insert(t##_TREE *list, t *element); \ decl void pr##_Tree_Del(t *element); \ \ decl void pr##_Tree_AddChild(t *where, t *element); \ decl void pr##_Tree_InsertChild(t *where, t *element); \ \ decl int pr##_Tree_HasChildElement(const t *who, const t *element); \ decl void pr##_Tree_ClearChildren(t *element); \
#define GWEN_TREE_FUNCTIONS | ( | t, | |||
pr | ) |
Use this inside your code files (*.c). Actually implements the functions for which the prototypes have been defined via GWEN_TREE_FUNCTION_DEFS.
#define GWEN_TREE_INIT | ( | t, | |||
element | ) | element->_tree_element=GWEN_TreeElement_new(element); |
typedef struct GWEN_TREE_ELEMENT GWEN_TREE_ELEMENT |
GWENHYWFAR_API void GWEN_Tree_Add | ( | GWEN_TREE * | l, | |
GWEN_TREE_ELEMENT * | el | |||
) |
Adds (appends) a toplevel tree element. (This operation is also called "append" or "push_back" elsewhere.)
Definition at line 60 of file tree.c.
References DBG_ERROR, GWEN_LOGDOMAIN, and NULL.
Referenced by GWEN_Tree_AddList().
GWENHYWFAR_API void GWEN_Tree_AddChild | ( | GWEN_TREE_ELEMENT * | where, | |
GWEN_TREE_ELEMENT * | el | |||
) |
Add a child below the given element.
Definition at line 164 of file tree.c.
References DBG_ERROR, and GWEN_LOGDOMAIN.
Adds (appends) the second list to the end of the first list. (This operation is also called "append" or "concatenate" elsewhere.)
Definition at line 85 of file tree.c.
References GWEN_Tree_Add(), GWEN_Tree_Del(), and GWEN_TREE_ELEMENT.
GWENHYWFAR_API void GWEN_Tree_Del | ( | GWEN_TREE_ELEMENT * | el | ) |
Deletes (removes) a tree element from the tree it used to belong to. The tree 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.)
Definition at line 121 of file tree.c.
References DBG_ERROR, GWEN_LOGDOMAIN, and NULL.
Referenced by GWEN_Tree_AddList(), and GWEN_TreeElement_free().
GWENHYWFAR_API void GWEN_Tree_free | ( | GWEN_TREE * | l | ) |
Free (delete) an existing list. The list elements are untouched by this function; they need to be freed beforehand.
Definition at line 45 of file tree.c.
References GWEN_FREE_OBJECT.
GWENHYWFAR_API int GWEN_Tree_GetCount | ( | const GWEN_TREE * | l | ) |
GWENHYWFAR_API void* GWEN_Tree_GetFirst | ( | const GWEN_TREE * | l | ) |
GWENHYWFAR_API void* GWEN_Tree_GetLast | ( | const GWEN_TREE * | l | ) |
GWENHYWFAR_API void GWEN_Tree_Insert | ( | GWEN_TREE * | l, | |
GWEN_TREE_ELEMENT * | el | |||
) |
Inserts (prepends) a toplevel tree element at the beginning of the list. (This operation is also called "prepend" or "push_front" elsewhere.)
Definition at line 99 of file tree.c.
References DBG_ERROR, GWEN_LOGDOMAIN, and NULL.
GWENHYWFAR_API void GWEN_Tree_InsertChild | ( | GWEN_TREE_ELEMENT * | where, | |
GWEN_TREE_ELEMENT * | el | |||
) |
Insert a child below the given element.
Definition at line 189 of file tree.c.
References DBG_ERROR, GWEN_LOGDOMAIN, and NULL.
GWENHYWFAR_API GWEN_TREE* GWEN_Tree_new | ( | ) |
Allocate (create) a new empty list.
Definition at line 37 of file tree.c.
References GWEN_NEW_OBJECT.
GWENHYWFAR_API void GWEN_TreeElement_free | ( | GWEN_TREE_ELEMENT * | el | ) |
Free (delete) a list element structure.
Definition at line 241 of file tree.c.
References DBG_ERROR, GWEN_FREE_OBJECT, GWEN_LOGDOMAIN, and GWEN_Tree_Del().
GWENHYWFAR_API void* GWEN_TreeElement_GetBelow | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API uint32_t GWEN_TreeElement_GetChildrenCount | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API void* GWEN_TreeElement_GetFirstChild | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API void* GWEN_TreeElement_GetLastChild | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API void* GWEN_TreeElement_GetNext | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API void* GWEN_TreeElement_GetParent | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API void* GWEN_TreeElement_GetPrevious | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API GWEN_TREE_ELEMENT* GWEN_TreeElement_new | ( | void * | d | ) |
Allocate (create) a new list element structure.
Definition at line 230 of file tree.c.
References GWEN_NEW_OBJECT, and GWEN_TREE_ELEMENT.