PageRenderTime 20ms CodeModel.GetById 8ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/data_types/glib_n_ary_trees.e

http://github.com/tybor/Liberty
Specman e | 509 lines | 7 code | 117 blank | 385 comment | 0 complexity | 1bcc78d4ff557ae9a8cded46803fad23 MD5 | raw file
  1indexing
  2	copyright: "(C) 2005 Paolo Redaelli "
  3	license: "LGPL v2 or later"
  4	date: "$Date:$"
  5	revision: "$REvision:$"
  6
  7class GLIB_N_ARY_TREES
  8	-- Prev 	Up 	Home 	GLib Reference Manual 	Next
  9-- Top  |  Description
 10-- N-ary Trees
 11
 12-- N-ary Trees %G รข€”%@ trees of data with any number of branches.
 13	
 14-- Synopsis
 15
 16-- #include <glib.h>
 17
 18
 19--             GNode;
 20-- GNode*      g_node_new                      (gpointer data);
 21-- GNode*      g_node_copy                     (GNode *node);
 22-- gpointer    (*GCopyFunc)                    (gconstpointer src,
 23--                                              gpointer data);
 24-- GNode*      g_node_copy_deep                (GNode *node,
 25--                                              GCopyFunc copy_func,
 26--                                              gpointer data);
 27
 28-- GNode*      g_node_insert                   (GNode *parent,
 29--                                              gint position,
 30--                                              GNode *node);
 31-- GNode*      g_node_insert_before            (GNode *parent,
 32--                                              GNode *sibling,
 33--                                              GNode *node);
 34-- GNode*      g_node_insert_after             (GNode *parent,
 35--                                              GNode *sibling,
 36--                                              GNode *node);
 37-- #define     g_node_append                   (parent, node)
 38-- GNode*      g_node_prepend                  (GNode *parent,
 39--                                              GNode *node);
 40
 41-- #define     g_node_insert_data              (parent, position, data)
 42-- #define     g_node_insert_data_before       (parent, sibling, data)
 43-- #define     g_node_append_data              (parent, data)
 44-- #define     g_node_prepend_data             (parent, data)
 45
 46-- void        g_node_reverse_children         (GNode *node);
 47-- void        g_node_traverse                 (GNode *root,
 48--                                              GTraverseType order,
 49--                                              GTraverseFlags flags,
 50--                                              gint max_depth,
 51--                                              GNodeTraverseFunc func,
 52--                                              gpointer data);
 53-- enum        GTraverseFlags;
 54-- gboolean    (*GNodeTraverseFunc)            (GNode *node,
 55--                                              gpointer data);
 56-- void        g_node_children_foreach         (GNode *node,
 57--                                              GTraverseFlags flags,
 58--                                              GNodeForeachFunc func,
 59--                                              gpointer data);
 60-- void        (*GNodeForeachFunc)             (GNode *node,
 61--                                              gpointer data);
 62
 63-- GNode*      g_node_get_root                 (GNode *node);
 64-- GNode*      g_node_find                     (GNode *root,
 65--                                              GTraverseType order,
 66--                                              GTraverseFlags flags,
 67--                                              gpointer data);
 68-- GNode*      g_node_find_child               (GNode *node,
 69--                                              GTraverseFlags flags,
 70--                                              gpointer data);
 71-- gint        g_node_child_index              (GNode *node,
 72--                                              gpointer data);
 73-- gint        g_node_child_position           (GNode *node,
 74--                                              GNode *child);
 75-- #define     g_node_first_child              (node)
 76-- GNode*      g_node_last_child               (GNode *node);
 77-- GNode*      g_node_nth_child                (GNode *node,
 78--                                              guint n);
 79-- GNode*      g_node_first_sibling            (GNode *node);
 80-- #define     g_node_next_sibling             (node)
 81-- #define     g_node_prev_sibling             (node)
 82-- GNode*      g_node_last_sibling             (GNode *node);
 83
 84-- #define     G_NODE_IS_LEAF                  (node)
 85-- #define     G_NODE_IS_ROOT                  (node)
 86-- guint       g_node_depth                    (GNode *node);
 87-- guint       g_node_n_nodes                  (GNode *root,
 88--                                              GTraverseFlags flags);
 89-- guint       g_node_n_children               (GNode *node);
 90-- gboolean    g_node_is_ancestor              (GNode *node,
 91--                                              GNode *descendant);
 92-- guint       g_node_max_height               (GNode *root);
 93
 94-- void        g_node_unlink                   (GNode *node);
 95-- void        g_node_destroy                  (GNode *root);
 96
 97-- void        g_node_push_allocator           (GAllocator *allocator);
 98-- void        g_node_pop_allocator            (void);
 99
100-- Description
101
102-- The GNode struct and its associated functions provide a N-ary tree data structure, where nodes in the tree can contain arbitrary data.
103
104-- To create a new tree use g_node_new().
105
106-- To insert a node into a tree use g_node_insert(), g_node_insert_before(), g_node_append() and g_node_prepend().
107
108-- To create a new node and insert it into a tree use g_node_insert_data(), g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data().
109
110-- To reverse the children of a node use g_node_reverse_children().
111
112-- To find a node use g_node_get_root(), g_node_find(), g_node_find_child(), g_node_child_index(), g_node_child_position(), g_node_first_child(), g_node_last_child(), g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() or g_node_last_sibling().
113
114-- To get information about a node or tree use G_NODE_IS_LEAF(), G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
115
116-- To traverse a tree, calling a function for each node visited in the traversal, use g_node_traverse() or g_node_children_foreach().
117
118-- To remove a node or subtree from a tree use g_node_unlink() or g_node_destroy().
119-- Details
120-- GNode
121
122-- typedef struct {
123--   gpointer data;
124--   GNode	  *next;
125--   GNode	  *prev;
126--   GNode	  *parent;
127--   GNode	  *children;
128-- } GNode;
129
130-- The GNode struct represents one node in a N-ary Tree. The data field contains the actual data of the node. The next and prev fields point to the node's siblings (a sibling is another GNode with the same parent). The parent field points to the parent of the GNode, or is NULL if the GNode is the root of the tree. The children field points to the first child of the GNode. The other children are accessed by using the next pointer of each child.
131-- g_node_new ()
132
133-- GNode*      g_node_new                      (gpointer data);
134
135-- Creates a new GNode containing the given data. Used to create the first node in a tree.
136-- data : 	the data of the new node.
137-- Returns : 	a new GNode.
138-- g_node_copy ()
139
140-- GNode*      g_node_copy                     (GNode *node);
141
142-- Recursively copies a GNode (but does not deep-copy the data inside the nodes, see g_node_copy_deep() if you need that).
143-- node : 	a GNode.
144-- Returns : 	a new GNode containing the same data pointers.
145-- GCopyFunc ()
146
147-- gpointer    (*GCopyFunc)                    (gconstpointer src,
148--                                              gpointer data);
149
150-- A function of this signature is used to copy the node data when doing a deep-copy of a tree.
151-- src : 	A pointer to the data which should be copied.
152-- data : 	Additional data.
153-- Returns : 	A pointer to the copy.
154
155-- Since 2.4
156-- g_node_copy_deep ()
157
158-- GNode*      g_node_copy_deep                (GNode *node,
159--                                              GCopyFunc copy_func,
160--                                              gpointer data);
161
162-- Recursively copies a GNode and its data.
163
164-- node : 	a GNode
165-- copy_func : 	the function which is called to copy the data inside each node, or NULL to use the original data.
166-- data : 	data to pass to copy_func
167-- Returns : 	a new GNode containing copies of the data in node.
168
169-- Since 2.4
170-- g_node_insert ()
171
172-- GNode*      g_node_insert                   (GNode *parent,
173--                                              gint position,
174--                                              GNode *node);
175
176-- Inserts a GNode beneath the parent at the given position.
177-- parent : 	the GNode to place node under.
178-- position : 	the position to place node at, with respect to its siblings. If position is -1, node is inserted as the last child of parent.
179-- node : 	the GNode to insert.
180-- Returns : 	the inserted GNode.
181-- g_node_insert_before ()
182
183-- GNode*      g_node_insert_before            (GNode *parent,
184--                                              GNode *sibling,
185--                                              GNode *node);
186
187-- Inserts a GNode beneath the parent before the given sibling.
188-- parent : 	the GNode to place node under.
189-- sibling : 	the sibling GNode to place node before. If sibling is NULL, the node is inserted as the last child of parent.
190-- node : 	the GNode to insert.
191-- Returns : 	the inserted GNode.
192-- g_node_insert_after ()
193
194-- GNode*      g_node_insert_after             (GNode *parent,
195--                                              GNode *sibling,
196--                                              GNode *node);
197
198-- Inserts a GNode beneath the parent after the given sibling.
199-- parent : 	the GNode to place node under.
200-- sibling : 	the sibling GNode to place node after. If sibling is NULL, the node is inserted as the first child of parent.
201-- node : 	the GNode to insert.
202-- Returns : 	the inserted GNode.
203-- g_node_append()
204
205-- #define     g_node_append(parent, node)
206
207-- Inserts a GNode as the last child of the given parent.
208-- parent : 	the GNode to place the new GNode under.
209-- node : 	the GNode to insert.
210-- Returns : 	the inserted GNode.
211-- g_node_prepend ()
212
213-- GNode*      g_node_prepend                  (GNode *parent,
214--                                              GNode *node);
215
216-- Inserts a GNode as the first child of the given parent.
217-- parent : 	the GNode to place the new GNode under.
218-- node : 	the GNode to insert.
219-- Returns : 	the inserted GNode.
220-- g_node_insert_data()
221
222-- #define     g_node_insert_data(parent, position, data)
223
224-- Inserts a new GNode at the given position.
225-- parent : 	the GNode to place the new GNode under.
226-- position : 	the position to place the new GNode at. If position is -1, the new GNode is inserted as the last child of parent.
227-- data : 	the data for the new GNode.
228-- Returns : 	the new GNode.
229-- g_node_insert_data_before()
230
231-- #define     g_node_insert_data_before(parent, sibling, data)
232
233-- Inserts a new GNode before the given sibling.
234-- parent : 	the GNode to place the new GNode under.
235-- sibling : 	the sibling GNode to place the new GNode before.
236-- data : 	the data for the new GNode.
237-- Returns : 	the new GNode.
238-- g_node_append_data()
239
240-- #define     g_node_append_data(parent, data)
241
242-- Inserts a new GNode as the last child of the given parent.
243-- parent : 	the GNode to place the new GNode under.
244-- data : 	the data for the new GNode.
245-- Returns : 	the new GNode.
246-- g_node_prepend_data()
247
248-- #define     g_node_prepend_data(parent, data)
249
250-- Inserts a new GNode as the first child of the given parent.
251-- parent : 	the GNode to place the new GNode under.
252-- data : 	the data for the new GNode.
253-- Returns : 	the new GNode.
254-- g_node_reverse_children ()
255
256-- void        g_node_reverse_children         (GNode *node);
257
258-- Reverses the order of the children of a GNode. (It doesn't change the order of the grandchildren.)
259-- node : 	a GNode.
260-- g_node_traverse ()
261
262-- void        g_node_traverse                 (GNode *root,
263--                                              GTraverseType order,
264--                                              GTraverseFlags flags,
265--                                              gint max_depth,
266--                                              GNodeTraverseFunc func,
267--                                              gpointer data);
268
269-- Traverses a tree starting at the given root GNode. It calls the given function for each node visited. The traversal can be halted at any point by returning TRUE from func.
270-- root : 	the root GNode of the tree to traverse.
271-- order : 	the order in which nodes are visited - G_IN_ORDER, G_PRE_ORDER, G_POST_ORDER, or G_LEVEL_ORDER.
272-- flags : 	which types of children are to be visited, one of G_TRAVERSE_ALL, G_TRAVERSE_LEAVES and G_TRAVERSE_NON_LEAVES.
273-- max_depth : 	the maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If depth is 1, only the root is visited. If depth is 2, the root and its children are visited. And so on.
274-- func : 	the function to call for each visited GNode.
275-- data : 	user data to pass to the function.
276-- enum GTraverseFlags
277
278-- typedef enum
279-- {
280--   G_TRAVERSE_LEAVES     = 1 << 0,
281--   G_TRAVERSE_NON_LEAVES = 1 << 1,
282--   G_TRAVERSE_ALL        = G_TRAVERSE_LEAVES | G_TRAVERSE_NON_LEAVES,
283--   G_TRAVERSE_MASK       = 0x03,
284--   G_TRAVERSE_LEAFS      = G_TRAVERSE_LEAVES,
285--   G_TRAVERSE_NON_LEAFS  = G_TRAVERSE_NON_LEAVES
286-- } GTraverseFlags;
287
288-- Specifies which nodes are visited during several of the tree functions, including g_node_traverse() and g_node_find().
289-- G_TRAVERSE_LEAVES 	only leaf nodes should be visited. This name has been introduced in 2.6, for older version use G_TRAVERSE_LEAFS.
290-- G_TRAVERSE_NON_LEAVES 	only non-leaf nodes should be visited. This name has been introduced in 2.6, for older version use G_TRAVERSE_NON_LEAFS.
291-- G_TRAVERSE_ALL 	all nodes should be visited.
292-- G_TRAVERSE_MASK 	
293-- G_TRAVERSE_LEAFS 	identical to G_TRAVERSE_LEAVES
294-- G_TRAVERSE_NON_LEAFS 	identical to G_TRAVERSE_NON_LEAVES
295-- GNodeTraverseFunc ()
296
297-- gboolean    (*GNodeTraverseFunc)            (GNode *node,
298--                                              gpointer data);
299
300-- Specifies the type of function passed to g_node_traverse(). The function is called with each of the nodes visited, together with the user data passed to g_node_traverse(). If the function returns TRUE, then the traversal is stopped.
301-- node : 	a GNode.
302-- data : 	user data passed to g_node_traverse().
303-- Returns : 	TRUE to stop the traversal.
304-- g_node_children_foreach ()
305
306-- void        g_node_children_foreach         (GNode *node,
307--                                              GTraverseFlags flags,
308--                                              GNodeForeachFunc func,
309--                                              gpointer data);
310
311-- Calls a function for each of the children of a GNode. Note that it doesn't descend beneath the child nodes.
312-- node : 	a GNode.
313-- flags : 	which types of children are to be visited, one of G_TRAVERSE_ALL, G_TRAVERSE_LEAVES and G_TRAVERSE_NON_LEAVES.
314-- func : 	the function to call for each visited node.
315-- data : 	user data to pass to the function.
316-- GNodeForeachFunc ()
317
318-- void        (*GNodeForeachFunc)             (GNode *node,
319--                                              gpointer data);
320
321-- Specifies the type of function passed to g_node_children_foreach(). The function is called with each child node, together with the user data passed to g_node_children_foreach().
322-- node : 	a GNode.
323-- data : 	user data passed to g_node_children_foreach().
324-- g_node_get_root ()
325
326-- GNode*      g_node_get_root                 (GNode *node);
327
328-- Gets the root of a tree.
329-- node : 	a GNode.
330-- Returns : 	the root of the tree.
331-- g_node_find ()
332
333-- GNode*      g_node_find                     (GNode *root,
334--                                              GTraverseType order,
335--                                              GTraverseFlags flags,
336--                                              gpointer data);
337
338-- Finds a GNode in a tree.
339-- root : 	the root GNode of the tree to search.
340-- order : 	the order in which nodes are visited - G_IN_ORDER, G_PRE_ORDER, G_POST_ORDER, or G_LEVEL_ORDER.
341-- flags : 	which types of children are to be searched, one of G_TRAVERSE_ALL, G_TRAVERSE_LEAVES and G_TRAVERSE_NON_LEAVES.
342-- data : 	the data to find.
343-- Returns : 	the found GNode, or NULL if the data is not found.
344-- g_node_find_child ()
345
346-- GNode*      g_node_find_child               (GNode *node,
347--                                              GTraverseFlags flags,
348--                                              gpointer data);
349
350-- Finds the first child of a GNode with the given data.
351-- node : 	a GNode.
352-- flags : 	which types of children are to be searched, one of G_TRAVERSE_ALL, G_TRAVERSE_LEAVES and G_TRAVERSE_NON_LEAVES.
353-- data : 	the data to find.
354-- Returns : 	the found child GNode, or NULL if the data is not found.
355-- g_node_child_index ()
356
357-- gint        g_node_child_index              (GNode *node,
358--                                              gpointer data);
359
360-- Gets the position of the first child of a GNode which contains the given data.
361-- node : 	a GNode.
362-- data : 	the data to find.
363-- Returns : 	the index of the child of node which contains data, or -1 if the data is not found.
364-- g_node_child_position ()
365
366-- gint        g_node_child_position           (GNode *node,
367--                                              GNode *child);
368
369-- Gets the position of a GNode with respect to its siblings. child must be a child of node. The first child is numbered 0, the second 1, and so on.
370-- node : 	a GNode.
371-- child : 	a child of node.
372-- Returns : 	the position of child with respect to its siblings.
373-- g_node_first_child()
374
375-- #define     g_node_first_child(node)
376
377-- Gets the first child of a GNode.
378-- node : 	a GNode.
379-- Returns : 	the last child of node, or NULL if node is NULL or has no children.
380-- g_node_last_child ()
381
382-- GNode*      g_node_last_child               (GNode *node);
383
384-- Gets the last child of a GNode.
385-- node : 	a GNode (must not be NULL).
386-- Returns : 	the last child of node, or NULL if node has no children.
387-- g_node_nth_child ()
388
389-- GNode*      g_node_nth_child                (GNode *node,
390--                                              guint n);
391
392-- Gets a child of a GNode, using the given index. The first child is at index 0. If the index is too big, NULL is returned.
393-- node : 	a GNode.
394-- n : 	the index of the desired child.
395-- Returns : 	the child of node at index n.
396-- g_node_first_sibling ()
397
398-- GNode*      g_node_first_sibling            (GNode *node);
399
400-- Gets the first sibling of a GNode. This could possibly be the node itself.
401-- node : 	a GNode.
402-- Returns : 	the first sibling of node.
403-- g_node_next_sibling()
404
405-- #define     g_node_next_sibling(node)
406
407-- Gets the next sibling of a GNode.
408-- node : 	a GNode.
409-- Returns : 	the next sibling of node, or NULL if node is NULL.
410-- g_node_prev_sibling()
411
412-- #define     g_node_prev_sibling(node)
413
414-- Gets the previous sibling of a GNode.
415-- node : 	a GNode.
416-- Returns : 	the previous sibling of node, or NULL if node is NULL.
417-- g_node_last_sibling ()
418
419-- GNode*      g_node_last_sibling             (GNode *node);
420
421-- Gets the last sibling of a GNode. This could possibly be the node itself.
422-- node : 	a GNode.
423-- Returns : 	the last sibling of node.
424-- G_NODE_IS_LEAF()
425
426-- #define	 G_NODE_IS_LEAF(node)	(((GNode*) (node))->children == NULL)
427
428-- Returns TRUE if a GNode is a leaf node.
429-- node : 	a GNode.
430-- Returns : 	TRUE if the GNode is a leaf node (i.e. it has no children).
431-- G_NODE_IS_ROOT()
432
433-- #define     G_NODE_IS_ROOT(node)
434
435-- Returns TRUE if a GNode is the root of a tree.
436-- node : 	a GNode.
437-- Returns : 	TRUE if the GNode is the root of a tree (i.e. it has no parent or siblings).
438-- g_node_depth ()
439
440-- guint       g_node_depth                    (GNode *node);
441
442-- Gets the depth of a GNode.
443
444-- If node is NULL the depth is 0. The root node has a depth of 1. For the children of the root node the depth is 2. And so on.
445-- node : 	a GNode.
446-- Returns : 	the depth of the GNode.
447-- g_node_n_nodes ()
448
449-- guint       g_node_n_nodes                  (GNode *root,
450--                                              GTraverseFlags flags);
451
452-- Gets the number of nodes in a tree.
453-- root : 	a GNode.
454-- flags : 	which types of children are to be counted, one of G_TRAVERSE_ALL, G_TRAVERSE_LEAVES and G_TRAVERSE_NON_LEAVES.
455-- Returns : 	the number of nodes in the tree.
456-- g_node_n_children ()
457
458-- guint       g_node_n_children               (GNode *node);
459
460-- Gets the number of children of a GNode.
461-- node : 	a GNode.
462-- Returns : 	the number of children of node.
463-- g_node_is_ancestor ()
464
465-- gboolean    g_node_is_ancestor              (GNode *node,
466--                                              GNode *descendant);
467
468-- Returns TRUE if node is an ancestor of descendant. This is true if node is the parent of descendant, or if node is the grandparent of descendant etc.
469-- node : 	a GNode.
470-- descendant : 	a GNode.
471-- Returns : 	TRUE if node is an ancestor of descendant.
472-- g_node_max_height ()
473
474-- guint       g_node_max_height               (GNode *root);
475
476-- Gets the maximum height of all branches beneath a GNode. This is the maximum distance from the GNode to all leaf nodes.
477
478-- If root is NULL, 0 is returned. If root has no children, 1 is returned. If root has children, 2 is returned. And so on.
479-- root : 	a GNode.
480-- Returns : 	the maximum height of the tree beneath root.
481-- g_node_unlink ()
482
483-- void        g_node_unlink                   (GNode *node);
484
485-- Unlinks a GNode from a tree, resulting in two separate trees.
486-- node : 	the GNode to unlink, which becomes the root of a new tree.
487-- g_node_destroy ()
488
489-- void        g_node_destroy                  (GNode *root);
490
491-- Removes the GNode and its children from the tree, freeing any memory allocated.
492-- root : 	the root of the tree/subtree to destroy.
493-- g_node_push_allocator ()
494
495-- void        g_node_push_allocator           (GAllocator *allocator);
496
497-- Sets the allocator to use to allocate GNode elements. Use g_node_pop_allocator() to restore the previous allocator.
498
499-- Note that this function is not available if GLib has been compiled with --disable-mem-pools
500-- allocator : 	the GAllocator to use when allocating GNode elements.
501-- g_node_pop_allocator ()
502
503-- void        g_node_pop_allocator            (void);
504
505-- Restores the previous GAllocator, used when allocating GNode elements.
506
507-- Note that this function is not available if GLib has been compiled with --disable-mem-pools
508end
509