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