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.
  52 If
  53 .Fa direction
  54 is instead set to
  55 .Dv AVL_BEFORE ,
  56 then the node that would have logically preceded it is returned.
  57 .Pp
  58 When there is no nearest node, for example,
  59 .Dv AVL_AFTER
  60 is specified and the entry would have been the last node in the tree,
  61 then
  62 .Sy NULL is returned .
  63 .Pp
  64 If the tree is modified between a call to
  65 .Xr avl_find 3AVL
  66 and
  67 .Fn avl_nearest ,
  68 then the value of
  69 .Fa where
  70 from
  71 .Xr avl_find 3AVL
  72 will no longer be valid and
  73 .Xr avl_find 3AVL
  74 must be called again.
  75 .Sh RETURN VALUES
  76 The
  77 .Fn avl_nearest
  78 function returns the node that is closest or
  79 .Sy NULL
  80 if there is not a matching one.
  81 .Sh EXAMPLES
  82 See the
  83 .Sy EXAMPLES
  84 section in
  85 .Xr libavl 3LIB .
  86 .Sh INTERFACE STABILITY
  87 .Sy Committed
  88 .Sh MT-Level
  89 See
  90 .Sx Locking
  91 in
  92 .Xr libavl 3LIB .
  93 .Sh SEE ALSO
  94 .Xr libavl 3LIB