Next: , Previous: Chain status, Up: Chains


13.4 Selecting nodes of a chain

— Function: Chainlink * chain_first (const Chain *chain)
— Function: Chainlink * chain_front (const Chain *chain)

Return a reference to the first node in chain, or a null pointer if chain has no nodes.

— Function: Chainlink * chain_last (const Chain *chain)
— Function: Chainlink * chain_rear (const Chain *chain)

Return a reference to the last node in chain, or a null pointer if chain has no nodes.

— Function: Chainlink * chain_nth (const Chain *chain, ssize_t n)

Returns a reference to the nth node in chain. n must be non-negative and less than the length of chain. Note that since a ‘Chain’ is a doubly-linked list, this operation can be performed in time O(n/2), where n is the length of the chain.

— Function: Chainlink * chain_pred (const Chain *chain, const Chainlink *node)
— Function: Chainlink * chain_succ (const Chain *chain, const Chainlink *node)

Return a reference to the predecessor or successor respectively of node, which must be a member of chain. Return a null pointer if there is no predecessor or successor respectively for node.

— Function: Chainlink * chain_cpred (const Chain *chain, const Chainlink *node)
— Function: Chainlink * chain_csucc (const Chain *chain, const Chainlink *node)

Behave as ‘chain_pred’ and ‘chain_succ’ respectively, with the exception that they encode circular motion (as for a ring buffer): if chain and node are valid, a null pointer will never be returned.

— Function: int chain_member (const Chain *chain, const Chainlink *node)

Returns 1 if node is a member of chain, and zero otherwise.

It is also possible to search for a node whose data are equal to some particular value. Since a chain is a generic container, this implies that the programmer must supply the comparison function.

— Function pointer: Chain_compare_f int (*) (const void *left, const void *right, void *args)

The type of a function pointer used to compare members of a chain. The function is passed the addresses of two objects, left and right, as well as a user-supplied pointer to parameters, args. The function should return zero if left and right are equal, a negative value if left is less than right, and a positive value if left is greater than right.

— Function: Chainlink * chain_find (const Chain *chain, const void *target, Chain_compare_f cmp, void *cmp_args)
— Function: Chainlink * chain_rfind (const Chain *chain, const void *target, Chain_compare_f cmp, void *cmp_args)

Returns a reference to a member of chain whose data section compares equal (according to cmp) to target. cmp_args is passed as the last argument to cmp. Note that ‘chain_find’ starts searching from the front of chain, while ‘chain_rfind’ starts from the back. If no matching node can be found, a null pointer is returned.