share/man/man3avl/avl_nearest.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_NEAREST 3AVL
  16 .Os
  17 .Sh NAME
  18 .Nm avl_nearest
  19 .Nd find the nearest node in an AVL tree
  20 .Sh SYNOPSIS
  21 .Lb libavl
  22 .In sys/avl.h
  23 .Ft void *
  24 .Fo avl_nearest
  25 .Fa "avl_tree_t *tree"
  26 .Fa "avl_index_t where"
  27 .Fa "int direction"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fa avl_nearest
  32 function returns the closest node in
  33 .Fa tree
  34 before or after the insertion point specified by
  35 .Fa where .
  36 .Pp
  37 The value of
  38 .Fa where
  39 is obtained when a
  40 .Pf non- Dv NULL
  41 pointer is passed in to the
  42 .Fa where
  43 argument of
  44 .Xr avl_find 3AVL
  45 and it fails to find an entry in the tree.
  46 .Pp
  47 If
  48 .Fa direction
  49 is set to
  50 .Dv AVL_AFTER ,
  51 then the node that would logically have followed it will be returned. If
  52 .Fa direction
  53 is instead set to
  54 .Dv AVL_BEFORE ,
  55 then the node that would have logically preceded it is returned.
  56 .Pp
  57 When there is no nearest node, for example,
  58 .Dv AVL_AFTER
  59 is specified and the entry would have been the last node in the tree,
  60 then
  61 .Sy NULL is returned .
  62 .Pp
  63 If the tree is modified between a call to
  64 .Xr avl_find 3AVL
  65 and
  66 .Fn avl_nearest ,
  67 then the value of
  68 .Fa where
  69 from
  70 .Xr avl_find 3AVL
  71 will no longer be valid and
  72 .Xr avl_find 3AVL
  73 must be called again.
  74 .Sh RETURN VALUES
  75 The
  76 .Fn avl_nearest
  77 function returns the node that is closest or
  78 .Sy NULL
  79 if there is not a matching one.
  80 .Sh EXAMPLES
  81 See the
  82 .Sy EXAMPLES
  83 section in
  84 .Xr libavl 3LIB .
  85 .Sh INTERFACE STABILITY
  86 .Sy Committed
  87 .Sh MT-Level
  88 See
  89 .Sx Locking
  90 in
  91 .Xr libavl 3LIB .
  92 .Sh SEE ALSO
  93 .Xr libavl 3LIB