usr/src/man/man3avl/avl_first.3avl

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 07, 2015
  15 .Dt AVL_FIRST 3AVL
  16 .Os
  17 .Sh NAME
  18 .Nm avl_first ,
  19 .Nm AVL_NEXT ,
  20 .Nm AVL_PREV ,
  21 .Nm avl_last
  22 .Nd get the first, next, previous, and last entries from an AVL tree
  23 .Sh SYNOPSIS
  24 .Lb libavl
  25 .In sys/avl.h
  26 .Ft void *
  27 .Fo avl_first
  28 .Fa "avl_tree_t *tree"
  29 .Fc
  30 .Ft void *
  31 .Fo avl_last
  32 .Fa "avl_tree_t *tree"
  33 .Fc
  34 .Ft void *
  35 .Fo AVL_NEXT
  36 .Fa "avl_tree_t *tree"
  37 .Fa "void *node"
  38 .Fc
  39 .Ft void *
  40 .Fo AVL_PREV
  41 .Fa "avl_tree_t *tree"
  42 .Fa "void *node"
  43 .Fc
  44 .Sh DESCRIPTION
  45 The
  46 .Fn avl_first
  47 and
  48 .Fn avl_last
  49 respectively return the first and last entry in the tree specified by
  50 .Fa tree .
  51 Order in the tree is determined by the comparison function that was
  52 specified at the time the tree was created with
  53 .Xr avl_create 3AVL .
  54 If
  55 .Fa tree
  56 is empty, then
  57 .Fn avl_first
  58 and
  59 .Fn avl_last
  60 return
  61 .Sy NULL .
  62 .Pp
  63 The
  64 .Fn AVL_NEXT
  65 and
  66 .Fn AVL_PREV
  67 functions are macros that may be used to obtain the next and previous
  68 entry following
  69 .Fa node
  70 in the AVL tree
  71 .Fa tree .
  72 If there is no next or previous node, for example, if one was at the
  73 beginning or end of the tree, then
  74 .Sy NULL
  75 is returned.
  76 .Pp
  77 These constructs are generally used as part of loops to iterate the
  78 tree.
  79 See the examples section in
  80 .Xr libavl 3LIB
  81 for more information on using this
  82 interface.
  83 .Sh RETURN VALUES
  84 The
  85 .Fn avl_first
  86 function returns a pointer to the first entry in the AVL tree
  87 .Fa tree
  88 or
  89 .Sy NULL
  90 if the AVL tree is empty.
  91 .Pp
  92 The
  93 .Fn avl_last
  94 function returns a pointer to the last entry in the AVL tree
  95 .Fa tree
  96 or
  97 .Sy NULL
  98 if the AVL tree is empty.
  99 .Pp
 100 The
 101 .Fn AVL_NEXT
 102 macro returns a pointer to the object in the tree that follows
 103 .Fa node .
 104 If
 105 .Fa node
 106 is the last entry in the tree,
 107 .Sy NULL
 108 is returned instead.
 109 .Pp
 110 The
 111 .Fn AVL_PREV
 112 macro returns a pointer to the object in the tree that precedes
 113 .Fa node .
 114 If
 115 .Fa node
 116 is the first entry in the tree,
 117 .Sy NULL
 118 is returned instead.
 119 .Sh EXAMPLES
 120 See the
 121 .Sy EXAMPLES
 122 section in
 123 .Xr libavl 3LIB .
 124 .Sh INTERFACE STABILITY
 125 .Sy Committed
 126 .Sh MT-Level
 127 See
 128 .Sx Locking
 129 in
 130 .Xr libavl 3LIB .
 131 .Sh SEE ALSO
 132 .Xr avl_create 3AVL ,
 133 .Xr libavl 3LIB