cons_node.h File Reference

Defines the structure and functions for cons nodes. More...

#include "cons.h"

Include dependency graph for cons_node.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	cons_node
	Structure representing a cons node. More...

Macros
#define	CONS_NODE(_cell_, _head_)   ((struct cons_node){.cell = (_cell_), .head = (_head_)})
	Constructs a cons node with the given cell and head.
#define	CONS_NODE_NULL   CONS_NODE(CONS(NULL, CONS_NIL), CONS_NIL)
	A null cons node with no parent and no children.

Functions
struct cons_node *	cons_car_node (struct cons_node *node)
	Accessor for the parent node (super-node) of a cons node.
struct cons_node *	cons_cdr_node (struct cons_node *node)
	Accessor for the next sibling node of a cons node.
struct cons_node *	cons_sub_node (struct cons_node *node)
	Accessor for the first child node (sub-node) of a cons node.
struct cons_node *	cons_node (struct cons_node *sub, struct cons_node *super)
	Constructs a cons node with the specified sub-node and new super-node.

Detailed Description

Defines the structure and functions for cons nodes.

This header file defines the structure of a cons node—a specialised data structure built on top of cons cells. Declares functions for manipulating cons nodes, including accessing parent and child nodes, and constructing a tree of cons nodes.

Definition in file cons_node.h.

Macro Definition Documentation

CONS_NODE

#define CONS_NODE	(		_cell_,
			_head_
	)		((struct cons_node){.cell = (_cell_), .head = (_head_)})

Constructs a cons node with the given cell and head.

Parameters

cell	The cons cell forming the basis of the node.
head	The list of child nodes (sub-nodes).

Returns

A new cons node initialised with the specified cell and head.

Definition at line 22 of file cons_node.h.

CONS_NODE_NULL

#define CONS_NODE_NULL   CONS_NODE(CONS(NULL, CONS_NIL), CONS_NIL)

A null cons node with no parent and no children.

This macro defines a null cons node, which is a node that has its cell initialised to a null cons cell (with car set to NULL and cdr set to CONS_NIL) and its head set to CONS_NIL, indicating that it has no children. This can be used as a default or placeholder node when constructing a tree of cons nodes.

Definition at line 32 of file cons_node.h.

Function Documentation

cons_car_node()

struct cons_node * cons_car_node

(

struct cons_node *

node

)

Accessor for the parent node (super-node) of a cons node.

Parameters

node	The cons node to access.

Return values

Pointer

to the parent node, or NULL if there is no parent.

Retrieves the parent node from the car field of the cons cell.

Definition at line 36 of file cons_node.c.

{ return (struct cons_node *)cons_car(&node->cell); }

cons_cdr_node()

struct cons_node * cons_cdr_node

(

struct cons_node *

node

)

Accessor for the next sibling node of a cons node.

Parameters

node	The cons node to access.

Returns

Pointer to the next sibling node, or NULL if there is no next sibling node.

Note

The next sibling node is stored in the cdr field of the node's cell. Up-casts the cdr field of the cons cell to a pointer to a node.

Definition at line 38 of file cons_node.c.

{ return node_from_cell(cons_cdr(&node->cell)); }

cons_node()

struct cons_node * cons_node	(	struct cons_node *	sub,
		struct cons_node *	super
	)

Constructs a cons node with the specified sub-node and new super-node.

Parameters

sub	The sub-node to be linked.
super	The new super-node to be linked.

Returns

Pointer to the super cons node for chaining.

Definition at line 45 of file cons_node.c.

                                                                            {
  /*
   * Prevent a node from being its own super-node. Avoids creating a
   * cycle in the tree, which would lead to undefined behaviour when
   * traversing. If the sub-node is the same as the super-node, the
   * function does not modify the tree structure.
   */
  if (sub == super)
    return super;
  struct cons_node *car = cons_car_node(sub);
  if (car != NULL) {
    /*
     * The sub-node already has a super-node. Remove the sub-node from
     * the list of sub-nodes of the current super-node. Remove it even
     * if the current super-node is the same as the new super-node,
     * because the sub-node may be in a different position in the list
     * of sub-nodes of the new super-node when re-constructing the same
     * sub-super linkage.
     */
    (void)cons_remove(&car->head, &sub->cell);
    cons_rplaca(&sub->cell, NULL);
  }
  if (super != NULL) {
    /*
     * The new super-node is not NULL. Prepend the sub-node to the list
     * of sub-nodes of the new super-node. Set the car field of the
     * sub-node to point to the new super-node.
     *
     * This could be redundant if the sub-node is already a sub-node of
     * the new super-node, but it is simpler to just do it
     * unconditionally than to check for that case.
     */
    (void)cons(&super->head, &sub->cell);
    cons_rplaca(&sub->cell, super);
  }
  return super;
}

cons_sub_node()

struct cons_node * cons_sub_node

(

struct cons_node *

node

)

Accessor for the first child node (sub-node) of a cons node.

Parameters

node	The cons node to access.

Returns

Pointer to the first child node, or NULL if there are no child nodes.

Note

The first child node is stored in the head field of the cons node. Up-casts the head field to a pointer to a node.

Definition at line 40 of file cons_node.c.

{ return node_from_cell(node->head); }