NAME

treestack.c - tree stack functions

Version Tag $Id: treestack.c,v 1.14 2006/02/06 19:55:47 db60 Exp $


DESCRIPTION

Provides operations for accessing and maintaining a stack of tree topologies.


treestack_cnt - RETURN COUNT OF TREES ON STACK

SYNOPSIS

long treestack_cnt(Treestack s);

DESCRIPTION

Return the number of trees currently stored on the stack s.

PARAMETERS

INPUT

s

The tree stack whose size we wish to know.

RETURN

Returns number of trees on stack s.


treestack_new - RETURN A NEW TREE STACK

SYNOPSIS

    Treestack treestack_new(void);

DESCRIPTION

Returns a new tree stack.

PARAMETERS

None.

RETURN

Returns a new, empty tree stack.


treestack_push - PUSH TREE ONTO TREE STACK

SYNOPSIS

    long treestack_push(Treestack *sp, const Branch *const barray,
    const long root);

DESCRIPTION

Push copy of a tree onto an existing tree stack. Will not push if its topology is already present on the stack. The stack will increase its own memory allocation if necessary.

PARAMETERS

INPUT

barray

Pointer to first element of array containing tree to be pushed.

root

Root branch number of tree to be pushed.

INOUT

sp

Pointer to tree stack that will receive a new copy of the tree.

RETURN

Returns 1 if the tree was pushed, or 0 if not.


treestack_pop - POP TREE OFF TREE STACK

SYNOPSIS

    long treestack_pop(Branch *barray, long *root, Treestack *sp);
    
=head2 DESCRIPTION

Pop a tree off a tree stack.

PARAMETERS

OUTPUT

barray

Pointer to first element of array to contain the popped tree. There must be sufficient space in this array prior to the call.

root

Pointer to scalar that will receive the index of the root in barray.

INOUT

sp

Pointer to tree stack from which we will pop the tree.

RETURN

Returns 1 if a tree was popped, or 0 if the stack was empty.


treestack_print - PRINT TREE STACK

SYNOPSIS

    long treestack_print(Treestack *sp, FILE *const outfp);

DESCRIPTION

Print all trees on a tree stack. The stack itself is not altered.

PARAMETERS

IN

sp

The stack to be printed.

OUTPUT

outfp

Pointer to the file to which we wish to output trees.

RETURN

Returns the number of trees printed.


treestack_dump - DUMP AND CLEAR TREE STACK

SYNOPSIS

    long treestack_dump(Treestack *sp, FILE *const outfp);

DESCRIPTION

Pop all trees off a stack and dump them.

PARAMETERS

OUTPUT

outfp

Pointer to the file to which we wish to output trees.

INOUT

sp

The stack to be emptied and dumped.

RETURN

Returns the number of trees dumped.


treestack_free - DEALLOCATE TREE STACK

SYNOPSIS

    void treestack_free(Treestack *sp);

DESCRIPTION

Clear a tree stack and deallocate dynamically allocated heap memory associated with it.

PARAMETERS

INOUT

sp

The stack to be emptied and deallocated.

RETURN

None.


treestack_clear - EMPTY TREE STACK

SYNOPSIS

    void treestack_clear(Treestack *sp);

DESCRIPTION

Empty a tree stack but do not deallocate memory associated with it. This memory will be available for re-use when trees are pushed onto the stack again.

PARAMETERS

INOUT

sp

The stack to be emptied.

RETURN

None.


treestack_transfer - TRANSFER TREES BETWEEN TREE STACKS

SYNOPSIS

    void treestack_transfer(Treestack *destp, Treestack *sourcep);

DESCRIPTION

Transfer one tree stack in its entirety to another. Order of the transferred trees is not preserved. Current contents and current order of the destination stack are preserved. The source stack is emptied but not deallocated.

PARAMETERS

INOUT

destp

Pointer to the stack to be added to.

sourcep

Pointer to the stack to be transferred to destp and cleared.

RETURN

None.