rbopenlist.3

.\" Copyright 2000 by Damian Ivereigh <damian@cisco.com>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.TH RBOPENLIST 3  "May 23, 2000" "GNU" "Linux Programmer's Manual"
.SH NAME
rbopenlist, rbreadlist, rbcloselist \- read from a red-black tree
.SH SYNOPSIS
.nf
.B #include <redblack.h>
.sp
.BI "RBLIST *rbopenlist ( const struct rbtree *" rb ");"
.sp
.BI "const void *rbreadlist ( RBLIST * " rblp ");"
.sp
.BI "void rbcloselist ( RBLIST * " rblp ");"
.sp
.RE
.fi
.SH DESCRIPTION
\fBrbopenlist\fP, \fBrbreadlist\fP, \fBrbcloselist\fP provide a simple
way to read from a redblack binary tree created by \fBrbinit(3)\fP.
.PP
\fBrbopenlist\fP initialises the list and returns a \fBRBLIST\fP
pointer that is used in subsequent calls to \fBrbreadlist\fP and
\fBrbcloselist\fP.
.PP
\fBrbreadlist\fP returns a pointer to the node data. Each subsequent
call returns the next node in the order specified by the tree.
.PP
\fBrbcloselist\fP simply frees up the memory used to allocate the \fBRBLIST\fP
data pointer.
.PP
.SH "RETURN VALUE"
\fBrbopenlist\fP returns a pointer to the new list structure, \fBNULL\fP
if there was insufficient memory to allocate the structure.
\fBrbreadlist\fP returns the next node data pointer in the tree, \fBNULL\fP
when there are no more entries.
\fBrbcloselist\fP has no return value.
.SH EXAMPLE
The following program inserts twelve random numbers into a binary
tree, then prints the numbers in order. 
.sp
.nf
    #include <redblack.h>
    #include <stdlib.h>
    #include <stdio.h>
    
    void *xmalloc(unsigned n)
    {
        void *p;
        p = malloc(n);
        if(p) return p;
        fprintf(stderr, "insufficient memory\\n");
        exit(1);
    }
    
    int compare(const void *pa, const void *pb, const void *config)
    {
        if(*(int *)pa < *(int *)pb) return -1;
        if(*(int *)pa > *(int *)pb) return 1;
        return 0;
    }
    
    int main()
    {
        int i, *ptr;
        void *val;
        struct rbtree *rb;
        RBLIST *rblist;
    
        srand(getpid());
    
        if ((rb=rbinit(compare, NULL))==NULL)
        {
            fprintf(stderr, "insufficient memory\\n");
            exit(1);
        }
    
        for (i = 0; i < 12; i++)
        {
            ptr = (int *)xmalloc(sizeof(int));
            *ptr = rand()&0xff;
            val = rbsearch((void *)ptr, rb);
            if(val == NULL) exit(1);
        }
    
        if ((rblist=rbopenlist(rb))==NULL)
        {
                fprintf(stderr, "insufficient memory from rbopenlist()\\n");
                exit(1);
        }

        while((val=rbreadlist(rblist)))
        {
                printf("%6d\\n", *(int *)val);
        }

        rbcloselist(rblist);

        rbdestroy(rb);
        
        return 0;
    }
.fi
.SH "SEE ALSO"
.BR rbinit (3),
.BR rbgen (1),
.BR tsearch (3).