code / tomo

   1 '\" t
   2 .\" Copyright (c) 2025 Bruce Hill
   3 .\" All rights reserved.
   4 .\"
   5 .TH List.binary_search 3 2025-11-29 "Tomo man-pages"
   6 .SH NAME
   7 List.binary_search \- binary search
   8 .SH LIBRARY
   9 Tomo Standard Library
  10 .SH SYNOPSIS
  11 .nf
  12 .BI List.binary_search\ :\ func(list:\ [T],\ by:\ func(x,y:&T->Int32)\ =\ T.compare\ ->\ Int)
  13 .fi
  14 .SH DESCRIPTION
  15 Performs a binary search on a sorted list.
  16 
  17 
  18 .SH ARGUMENTS
  19 
  20 .TS
  21 allbox;
  22 lb lb lbx lb
  23 l l l l.
  24 Name	Type	Description	Default
  25 list	[T]	The sorted list to search. 	-
  26 by	func(x,y:&T->Int32)	The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. 	T.compare
  27 .TE
  28 .SH RETURN
  29 Assuming the input list is sorted according to the given comparison function, return the index where the given item would be inserted to maintain the sorted order. That is, if the item is found, return its index, otherwise return the place where it would be found if it were inserted and the list were sorted.
  30 
  31 .SH EXAMPLES
  32 .EX
  33 assert [1, 3, 5, 7, 9].binary_search(5) == 3
  34 assert [1, 3, 5, 7, 9].binary_search(-999) == 1
  35 assert [1, 3, 5, 7, 9].binary_search(999) == 6
  36 .EE
  37 .SH SEE ALSO
  38 .BR Tomo-List (3)