share/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. See the examples section in
  79 .Xr libavl 3LIB
  80 for more information on using this
  81 interface.
  82 .Sh RETURN VALUES
  83 The
  84 .Fn avl_first
  85 function returns a pointer to the first entry in the AVL tree
  86 .Fa tree
  87 or
  88 .Sy NULL
  89 if the AVL tree is empty.
  90 .Pp
  91 The
  92 .Fn avl_last
  93 function returns a pointer to the last entry in the AVL tree
  94 .Fa tree
  95 or
  96 .Sy NULL
  97 if the AVL tree is empty.
  98 .Pp
  99 The
 100 .Fn AVL_NEXT
 101 macro returns a pointer to the object in the tree that follows
 102 .Fa node .
 103 If
 104 .Fa node
 105 is the last entry in the tree,
 106 .Sy NULL
 107 is returned instead.
 108 .Pp
 109 The
 110 .Fn AVL_PREV
 111 macro returns a pointer to the object in the tree that precedes
 112 .Fa node .
 113 If
 114 .Fa node
 115 is the first entry in the tree,
 116 .Sy NULL
 117 is returned instead.
 118 .Sh EXAMPLES
 119 See the
 120 .Sy EXAMPLES
 121 section in
 122 .Xr libavl 3LIB .
 123 .Sh INTERFACE STABILITY
 124 .Sy Committed
 125 .Sh MT-Level
 126 See
 127 .Sx Locking
 128 in
 129 .Xr libavl 3LIB .
 130 .Sh SEE ALSO
 131 .Xr avl_create 3AVL ,
 132 .Xr libavl 3LIB