- NAME
- DESCRIPTION
- treestack_cnt - RETURN COUNT OF TREES ON STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INPUT

- RETURN

- treestack_new - RETURN A NEW TREE STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS
- RETURN

- treestack_push - PUSH TREE ONTO TREE STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INPUT
- INOUT

- RETURN

- treestack_pop - POP TREE OFF TREE STACK

- SYNOPSIS
- PARAMETERS

- OUTPUT
- INOUT

- RETURN

- treestack_print - PRINT TREE STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- IN
- OUTPUT

- RETURN

- treestack_dump - DUMP AND CLEAR TREE STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- OUTPUT
- INOUT

- RETURN

- treestack_free - DEALLOCATE TREE STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INOUT

- RETURN

- treestack_clear - EMPTY TREE STACK

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INOUT

- RETURN

- treestack_transfer - TRANSFER TREES BETWEEN TREE STACKS

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INOUT

- RETURN

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