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