gwenhywfar
5.3.0
|
Typesafe Macros | |
#define | GWEN_TREE_ELEMENT(t) GWEN_TREE_ELEMENT *_tree_element; |
#define | GWEN_TREE_FUNCTION_LIB_DEFS_CONST(t, pr, decl) |
#define | GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl) |
#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_DEFS(t, pr) GWEN_TREE_FUNCTION_LIB_DEFS(t, pr, GWEN_DUMMY_EMPTY_ARG) |
#define | GWEN_TREE_FUNCTIONS(t, pr) |
#define | GWEN_TREE_INIT(t, element) element->_tree_element=GWEN_TreeElement_new(element); |
#define | GWEN_TREE_FINI(t, 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:
This defines all necessary data and function prototypes needed for list management.
The code file would look quite similar to the following:
Please note the three macros used in the code file:
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; |
#define GWEN_TREE_FINI | ( | t, | |
element | |||
) |
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".
#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 | |||
) |
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:
#define GWEN_TREE_FUNCTION_LIB_DEFS_CONST | ( | t, | |
pr, | |||
decl | |||
) |
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).
#define GWEN_TREE_FUNCTION_LIB_DEFS_NOCONST | ( | t, | |
pr, | |||
decl | |||
) |
#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.)
GWENHYWFAR_API void GWEN_Tree_AddChild | ( | GWEN_TREE_ELEMENT * | where, |
GWEN_TREE_ELEMENT * | el | ||
) |
Add a child below the given element.
GWENHYWFAR_API void GWEN_Tree_AddList | ( | GWEN_TREE * | dest, |
GWEN_TREE * | l | ||
) |
Adds (appends) the second list to the end of the first list. (This operation is also called "append" or "concatenate" elsewhere.) The second list will be empty upon return.
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.)
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.
GWENHYWFAR_API int GWEN_Tree_GetCount | ( | const GWEN_TREE * | l | ) |
Returns the number of elements in this list. This value is cached in the list structure, so this function is a cheap function.
GWENHYWFAR_API void* GWEN_Tree_GetFirst | ( | const GWEN_TREE * | l | ) |
Returns the data pointer of the first list element.
GWENHYWFAR_API void* GWEN_Tree_GetLast | ( | const GWEN_TREE * | l | ) |
Returns the data pointer of the last list element.
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.)
GWENHYWFAR_API void GWEN_Tree_InsertChild | ( | GWEN_TREE_ELEMENT * | where, |
GWEN_TREE_ELEMENT * | el | ||
) |
Insert a child below the given element.
GWENHYWFAR_API GWEN_TREE* GWEN_Tree_new | ( | void | ) |
Allocate (create) a new empty list.
GWENHYWFAR_API void GWEN_Tree_Replace | ( | GWEN_TREE_ELEMENT * | elToReplace, |
GWEN_TREE_ELEMENT * | elReplacement | ||
) |
Replaces a tree element with another one, so the replacement takes the place of the given element. The given element to replace is unlinked in the process and can be free'd. The replacement MUST NOT be part of any tree.
GWENHYWFAR_API void GWEN_TreeElement_free | ( | GWEN_TREE_ELEMENT * | el | ) |
Free (delete) a list element structure.
GWENHYWFAR_API void* GWEN_TreeElement_GetBelow | ( | const GWEN_TREE_ELEMENT * | el | ) |
Returns the element which is logically below the given one. The order of search is this:
GWENHYWFAR_API uint32_t GWEN_TreeElement_GetChildrenCount | ( | const GWEN_TREE_ELEMENT * | el | ) |
Returns the number of children of the given element
GWENHYWFAR_API void* GWEN_TreeElement_GetFirstChild | ( | const GWEN_TREE_ELEMENT * | el | ) |
Returns the first child of the given element.
GWENHYWFAR_API void* GWEN_TreeElement_GetLastChild | ( | const GWEN_TREE_ELEMENT * | el | ) |
Returns the last child of the given element.
GWENHYWFAR_API void* GWEN_TreeElement_GetNext | ( | const GWEN_TREE_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.
GWENHYWFAR_API void* GWEN_TreeElement_GetParent | ( | const GWEN_TREE_ELEMENT * | el | ) |
GWENHYWFAR_API void* GWEN_TreeElement_GetPrevious | ( | const GWEN_TREE_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.
GWENHYWFAR_API GWEN_TREE_ELEMENT* GWEN_TreeElement_new | ( | void * | d | ) |
Allocate (create) a new list element structure.