Macros For Typesafe Tree Handling

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_TREE2_FUNCTION_LIB_DEFS and following).
typedef struct GWEN_TREE2_ELEMENT	GWEN_TREE2_ELEMENT
GWENHYWFAR_API void	GWEN_Tree2_Unlink (GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void	GWEN_Tree2_Replace (GWEN_TREE2_ELEMENT *elToReplace, GWEN_TREE2_ELEMENT *elReplacement)
GWENHYWFAR_API void	GWEN_Tree2_AddChild (GWEN_TREE2_ELEMENT *where, GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void	GWEN_Tree2_InsertChild (GWEN_TREE2_ELEMENT *where, GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2_GetFirstChild (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2_GetLastChild (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API GWEN_TREE2_ELEMENT *	GWEN_Tree2Element_new (void *d)
GWENHYWFAR_API void	GWEN_Tree2Element_free (GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2Element_GetPrevious (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2Element_GetNext (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2Element_GetBelow (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2Element_GetFirstChild (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2Element_GetLastChild (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API void *	GWEN_Tree2Element_GetParent (const GWEN_TREE2_ELEMENT *el)
GWENHYWFAR_API uint32_t	GWEN_Tree2Element_GetChildrenCount (const GWEN_TREE2_ELEMENT *el)

Typesafe Macros
#define	GWEN_TREE2_ELEMENT(t)   GWEN_TREE2_ELEMENT *_tree2_element;
#define	GWEN_TREE2_FUNCTION_LIB_DEFS_CONST(t, pr, decl)
#define	GWEN_TREE2_FUNCTION_LIB_DEFS_NOCONST(t, pr, decl)
#define	GWEN_TREE2_FUNCTION_DEFS_CONST(t, pr)   GWEN_TREE2_FUNCTION_LIB_DEFS_CONST(t, pr, GWEN_DUMMY_EMPTY_ARG)
#define	GWEN_TREE2_FUNCTION_DEFS_NOCONST(t, pr)   GWEN_TREE2_FUNCTION_LIB_DEFS_NOCONST(t, pr, GWEN_DUMMY_EMPTY_ARG)
#define	GWEN_TREE2_FUNCTION_LIB_DEFS(t, pr, decl)
#define	GWEN_TREE2_FUNCTION_DEFS(t, pr)   GWEN_TREE2_FUNCTION_LIB_DEFS(t, pr, GWEN_DUMMY_EMPTY_ARG)
#define	GWEN_TREE2_FUNCTIONS(t, pr)
#define	GWEN_TREE2_INIT(t, element, pr)   element->_tree2_element=GWEN_Tree2Element_new(element);
#define	GWEN_TREE2_FINI(t, element, pr)

Detailed Description

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_TREE2_FUNCTION_DEFS(MYSTRUCT, MyStruct);

struct MYSTRUCT {
  GWEN_TREE2_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_TREE2_FUNCTIONS(MYSTRUCT, MyStruct)

MYSTRUCT *MyStruct_new(int myData) {
  MYSTRUCT *pMyStruct;

  pMyStruct=(MYSTRUCT*)malloc(sizeof(MYSTRUCT));
  memset(pMyStruct, 0, sizeof(MYSTRUCT));

  GWEN_TREE2_INIT(MYSTRUCT, pMyStruct)

  pMyStruct->myData=myData;
  return pMyStruct;
}

void MyStruct_free(MYSTRUCT *pMyStruct) {
  if (pMyStruct) {
    pMyStruct->myData=0;

    GWEN_TREE2_FINI(MYSTRUCT, pMyStruct)

    free(pMyStruct);
  }
}

Please note the three macros used in the code file:

• GWEN_TREE2_FUNCTIONS creates the functions for the list management
• GWEN_TREE2_INIT initializes the list data inside your struct to defined values
• GWEN_TREE2_FINI frees all ressources occupied by the list management code. Please note that this macro should be the last statement inside the destructor function before free()

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 tree 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.

Macro Definition Documentation

GWEN_TREE2_ELEMENT

#define GWEN_TREE2_ELEMENT

(

t

)

GWEN_TREE2_ELEMENT *_tree2_element;

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

Definition at line 251 of file tree2.h.

GWEN_TREE2_FINI

#define GWEN_TREE2_FINI	(		t,
			element,
			pr
	)

Value:

if (element && element->_tree2_element) { \
    pr##_Tree2_ClearChildren(element);\
    pr##_Tree2_Unlink(element);\
    GWEN_Tree2Element_free(element->_tree2_element); \
    element->_tree2_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". t is the base type id (e.g. "AF_ACCOUNT") element is the pointer to the element to fini pr ist the prefix of functions for this type (e.g. "AF_Account")

Definition at line 457 of file tree2.h.

Referenced by GWB_Context_free(), and GWEN_Test_Module_free().

GWEN_TREE2_FUNCTION_DEFS

#define GWEN_TREE2_FUNCTION_DEFS	(		t,
			pr
	)		GWEN_TREE2_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_TREE2_FUNCTION_LIB_DEFS.

Definition at line 345 of file tree2.h.

GWEN_TREE2_FUNCTION_DEFS_CONST

#define GWEN_TREE2_FUNCTION_DEFS_CONST	(		t,
			pr
	)		GWEN_TREE2_FUNCTION_LIB_DEFS_CONST(t, pr, GWEN_DUMMY_EMPTY_ARG)

Definition at line 282 of file tree2.h.

GWEN_TREE2_FUNCTION_DEFS_NOCONST

#define GWEN_TREE2_FUNCTION_DEFS_NOCONST	(		t,
			pr
	)		GWEN_TREE2_FUNCTION_LIB_DEFS_NOCONST(t, pr, GWEN_DUMMY_EMPTY_ARG)

Definition at line 285 of file tree2.h.

GWEN_TREE2_FUNCTION_LIB_DEFS

#define GWEN_TREE2_FUNCTION_LIB_DEFS	(		t,
			pr,
			decl
	)

Value:

GWEN_TREE2_FUNCTION_LIB_DEFS_CONST(t, pr, decl) \
  GWEN_TREE2_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_Tree2_Add(MYTYPE <em>element, MYTYPE_TREE *list);
  Adds (appends) a MYTYPE struct at the end of the given list. (We apologize for the unusual argument order here.)
• void MyType_Tree2_Unlink(MYTYPE *element);
  Removes a MyType struct from the list it is enlisted to.
• MYTYPE *MyType_Tree2_FirstChild(MYTYPE *element);
  Returns the first element of the given list.
• MYTYPE MyType_Tree2_Next(const MYTYPE <em>element);
  Returns the next list element to the given one (the successor) in its list.
• MYTYPE MyType_Tree2_Previous(const MYTYPE *element);
  Returns the previous list element to the given one (the predecessor) in its list.
• void MyType_Tree2_Clear(MYTYPE *element);
  Frees all entries of the given list. This function assumes that there is a function Mytype_free().
• MYTYPE_TREE *MyType_Tree2_new();
  Creates a new list of elements of MYTYPE type.
• void MyType_Tree2_free(MYTYPE_TREE *l);
  Clears and frees a list of elements of MYTYPE type. All objects inside the list are freed.

Definition at line 336 of file tree2.h.

GWEN_TREE2_FUNCTION_LIB_DEFS_CONST

#define GWEN_TREE2_FUNCTION_LIB_DEFS_CONST	(		t,
			pr,
			decl
	)

Value:

decl t* pr##_Tree2_GetNext(const t *element); \
  decl t* pr##_Tree2_GetPrevious(const t *element); \
  decl t* pr##_Tree2_GetBelow(const t *element); \
  decl t* pr##_Tree2_GetFirstChild(const t *element); \
  decl t* pr##_Tree2_GetLastChild(const t *element); \
  decl t* pr##_Tree2_GetParent(const t *element);

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 260 of file tree2.h.

GWEN_TREE2_FUNCTION_LIB_DEFS_NOCONST

#define GWEN_TREE2_FUNCTION_LIB_DEFS_NOCONST	(		t,
			pr,
			decl
	)

Value:

typedef GWEN_TREE2_ELEMENT t##_TREE2_ELEMENT; \
  \
  decl void pr##_Tree2_Unlink(t *element); \
  decl void pr##_Tree2_Replace(t *elToReplace, t *elReplacement); \
  \
  decl void pr##_Tree2_AddChild(t *where, t *element); \
  decl void pr##_Tree2_InsertChild(t *where, t *element); \
  \
  decl void pr##_Tree2_ClearChildren(t *element); \
  decl void pr##_Tree2_free(t *element);

Definition at line 269 of file tree2.h.

GWEN_TREE2_FUNCTIONS

#define GWEN_TREE2_FUNCTIONS	(		t,
			pr
	)

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

Definition at line 354 of file tree2.h.

GWEN_TREE2_INIT

#define GWEN_TREE2_INIT	(		t,
			element,
			pr
	)		element->_tree2_element=GWEN_Tree2Element_new(element);

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 445 of file tree2.h.

Referenced by GWB_Context_dup(), GWB_Context_new(), and GWEN_Test_Module_new().

Typedef Documentation

GWEN_TREE2_ELEMENT

typedef struct GWEN_TREE2_ELEMENT GWEN_TREE2_ELEMENT

Definition at line 155 of file tree2.h.

Function Documentation

GWEN_Tree2_AddChild()

GWENHYWFAR_API void GWEN_Tree2_AddChild	(	GWEN_TREE2_ELEMENT *	where,
		GWEN_TREE2_ELEMENT *	el
	)

Add a child below the given element.

Definition at line 122 of file tree2.c.

References NULL.

GWEN_Tree2_GetFirstChild()

GWENHYWFAR_API void* GWEN_Tree2_GetFirstChild

(

const GWEN_TREE2_ELEMENT *

el

)

Returns the data pointer of the first list element.

GWEN_Tree2_GetLastChild()

GWENHYWFAR_API void* GWEN_Tree2_GetLastChild

(

const GWEN_TREE2_ELEMENT *

el

)

Returns the data pointer of the last list element.

GWEN_Tree2_InsertChild()

GWENHYWFAR_API void GWEN_Tree2_InsertChild	(	GWEN_TREE2_ELEMENT *	where,
		GWEN_TREE2_ELEMENT *	el
	)

Insert a child below the given element.

Definition at line 137 of file tree2.c.

References NULL.

GWEN_Tree2_Replace()

GWENHYWFAR_API void GWEN_Tree2_Replace	(	GWEN_TREE2_ELEMENT *	elToReplace,
		GWEN_TREE2_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.

Definition at line 90 of file tree2.c.

References NULL.

GWEN_Tree2_Unlink()

GWENHYWFAR_API void GWEN_Tree2_Unlink

(

GWEN_TREE2_ELEMENT *

el

)

Unlinks (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 tree it used to belong to. (This operation is also called "remove" elsewhere.)

Definition at line 64 of file tree2.c.

References NULL.

GWEN_Tree2Element_free()

GWENHYWFAR_API void GWEN_Tree2Element_free

(

GWEN_TREE2_ELEMENT *

el

)

Free (delete) a list element structure.

Definition at line 51 of file tree2.c.

References DBG_ERROR, GWEN_FREE_OBJECT, and GWEN_LOGDOMAIN.

GWEN_Tree2Element_GetBelow()

GWENHYWFAR_API void* GWEN_Tree2Element_GetBelow

(

const GWEN_TREE2_ELEMENT *

el

)

Returns the element which is logically below the given one. The order of search is this:

• first child of the given element
• next neighbour of the given element
• loop for every parent: check next neighbour of the given element's parent (if any)

Definition at line 168 of file tree2.c.

References NULL.

GWEN_Tree2Element_GetChildrenCount()

GWENHYWFAR_API uint32_t GWEN_Tree2Element_GetChildrenCount

(

const GWEN_TREE2_ELEMENT *

el

)

Returns the number of children of the given element

GWEN_Tree2Element_GetFirstChild()

GWENHYWFAR_API void* GWEN_Tree2Element_GetFirstChild

(

const GWEN_TREE2_ELEMENT *

el

)

Returns the first child of the given element.

Definition at line 189 of file tree2.c.

References NULL.

GWEN_Tree2Element_GetLastChild()

GWENHYWFAR_API void* GWEN_Tree2Element_GetLastChild

(

const GWEN_TREE2_ELEMENT *

el

)

Returns the last child of the given element.

Definition at line 198 of file tree2.c.

References NULL.

GWEN_Tree2Element_GetNext()

GWENHYWFAR_API void* GWEN_Tree2Element_GetNext

(

const GWEN_TREE2_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.

Definition at line 159 of file tree2.c.

GWEN_Tree2Element_GetParent()

GWENHYWFAR_API void* GWEN_Tree2Element_GetParent

(

const GWEN_TREE2_ELEMENT *

el

)

Definition at line 207 of file tree2.c.

References NULL.

GWEN_Tree2Element_GetPrevious()

GWENHYWFAR_API void* GWEN_Tree2Element_GetPrevious

(

const GWEN_TREE2_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.

Definition at line 150 of file tree2.c.

GWEN_Tree2Element_new()

GWENHYWFAR_API GWEN_TREE2_ELEMENT* GWEN_Tree2Element_new

(

void *

d

)

Allocate (create) a new list element structure.

Definition at line 39 of file tree2.c.

References GWEN_NEW_OBJECT.