code / tomo

   1 '\" t
   2 .\" Copyright (c) 2026 Bruce Hill
   3 .\" All rights reserved.
   4 .\"
   5 .TH List 3 2026-03-11 "Tomo man-pages"
   6 .SH NAME
   7 List \- a Tomo type
   8 .SH LIBRARY
   9 Tomo Standard Library
  10 .fi
  11 .SH METHODS
  12 
  13 .TP
  14 .BI List.binary_search\ :\ func(list:\ [T],\ by:\ func(x,y:&T->Int32)\ =\ T.compare\ ->\ Int)
  15 Performs a binary search on a sorted list. 
  16 
  17 For more, see:
  18 .BR Tomo-List.binary_search (3)
  19 
  20 
  21 .TP
  22 .BI List.by\ :\ func(list:\ [T],\ step:\ Int\ ->\ [T])
  23 Creates a new list with elements spaced by the specified step value. 
  24 
  25 For more, see:
  26 .BR Tomo-List.by (3)
  27 
  28 
  29 .TP
  30 .BI List.clear\ :\ func(list:\ @[T]\ ->\ Void)
  31 Clears all elements from the list. 
  32 
  33 For more, see:
  34 .BR Tomo-List.clear (3)
  35 
  36 
  37 .TP
  38 .BI List.counts\ :\ func(list:\ [T]\ ->\ {T=Int})
  39 Counts the occurrences of each element in the list. 
  40 
  41 For more, see:
  42 .BR Tomo-List.counts (3)
  43 
  44 
  45 .TP
  46 .BI List.find\ :\ func(list:\ [T],\ target:\ T\ ->\ Int?)
  47 Finds the index of the first occurrence of an element (if any). 
  48 
  49 For more, see:
  50 .BR Tomo-List.find (3)
  51 
  52 
  53 .TP
  54 .BI List.from\ :\ func(list:\ [T],\ first:\ Int\ ->\ [T])
  55 Returns a slice of the list starting from a specified index. 
  56 
  57 For more, see:
  58 .BR Tomo-List.from (3)
  59 
  60 
  61 .TP
  62 .BI List.has\ :\ func(list:\ [T],\ target:\ T\ ->\ Bool)
  63 Checks if the list has an element. 
  64 
  65 For more, see:
  66 .BR Tomo-List.has (3)
  67 
  68 
  69 .TP
  70 .BI List.heap_pop\ :\ func(list:\ @[T],\ by:\ func(x,y:&T->Int32)\ =\ T.compare\ ->\ T?)
  71 Removes and returns the top element of a heap or \fBnone\fR if the list is empty. By default, this is the *minimum* value in the heap. 
  72 
  73 For more, see:
  74 .BR Tomo-List.heap_pop (3)
  75 
  76 
  77 .TP
  78 .BI List.heap_push\ :\ func(list:\ @[T],\ item:\ T,\ by\ =\ T.compare\ ->\ Void)
  79 Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap. 
  80 
  81 For more, see:
  82 .BR Tomo-List.heap_push (3)
  83 
  84 
  85 .TP
  86 .BI List.heapify\ :\ func(list:\ @[T],\ by:\ func(x,y:&T->Int32)\ =\ T.compare\ ->\ Void)
  87 Converts a list into a heap. 
  88 
  89 For more, see:
  90 .BR Tomo-List.heapify (3)
  91 
  92 
  93 .TP
  94 .BI List.insert\ :\ func(list:\ @[T],\ item:\ T,\ at:\ Int\ =\ 0\ ->\ Void)
  95 Inserts an element at a specified position in the list. 
  96 
  97 For more, see:
  98 .BR Tomo-List.insert (3)
  99 
 100 
 101 .TP
 102 .BI List.insert_all\ :\ func(list:\ @[T],\ items:\ [T],\ at:\ Int\ =\ 0\ ->\ Void)
 103 Inserts a list of items at a specified position in the list. 
 104 
 105 For more, see:
 106 .BR Tomo-List.insert_all (3)
 107 
 108 
 109 .TP
 110 .BI List.pop\ :\ func(list:\ &[T],\ index:\ Int\ =\ -1\ ->\ T?)
 111 Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter. 
 112 
 113 For more, see:
 114 .BR Tomo-List.pop (3)
 115 
 116 
 117 .TP
 118 .BI List.random\ :\ func(list:\ [T],\ random:\ func(min,max:Int64->Int64)?\ =\ none\ ->\ T?)
 119 Selects a random element from the list. 
 120 
 121 For more, see:
 122 .BR Tomo-List.random (3)
 123 
 124 
 125 .TP
 126 .BI List.remove_at\ :\ func(list:\ @[T],\ at:\ Int\ =\ -1,\ count:\ Int\ =\ 1\ ->\ Void)
 127 Removes elements from the list starting at a specified index. 
 128 
 129 For more, see:
 130 .BR Tomo-List.remove_at (3)
 131 
 132 
 133 .TP
 134 .BI List.remove_item\ :\ func(list:\ @[T],\ item:\ T,\ max_count:\ Int\ =\ -1\ ->\ Void)
 135 Removes all occurrences of a specified item from the list. 
 136 
 137 For more, see:
 138 .BR Tomo-List.remove_item (3)
 139 
 140 
 141 .TP
 142 .BI List.reversed\ :\ func(list:\ [T]\ ->\ [T])
 143 Returns a reversed slice of the list. 
 144 
 145 For more, see:
 146 .BR Tomo-List.reversed (3)
 147 
 148 
 149 .TP
 150 .BI List.sample\ :\ func(list:\ [T],\ count:\ Int,\ weights:\ [Num]?\ =\ none,\ random:\ func(->Num)?\ =\ none\ ->\ [T])
 151 Selects a sample of elements from the list, optionally with weighted probabilities. 
 152 
 153 For more, see:
 154 .BR Tomo-List.sample (3)
 155 
 156 
 157 .TP
 158 .BI List.shuffle\ :\ func(list:\ @[T],\ random:\ func(min,max:Int64->Int64)?\ =\ none\ ->\ Void)
 159 Shuffles the elements of the list in place. 
 160 
 161 For more, see:
 162 .BR Tomo-List.shuffle (3)
 163 
 164 
 165 .TP
 166 .BI List.shuffled\ :\ func(list:\ [T],\ random:\ func(min,max:Int64->Int64)?\ =\ none\ ->\ [T])
 167 Creates a new list with elements shuffled. 
 168 
 169 For more, see:
 170 .BR Tomo-List.shuffled (3)
 171 
 172 
 173 .TP
 174 .BI List.slice\ :\ func(list:\ [T],\ from:\ Int,\ to:\ Int\ ->\ [T])
 175 Returns a slice of the list spanning the given indices (inclusive). 
 176 
 177 For more, see:
 178 .BR Tomo-List.slice (3)
 179 
 180 
 181 .TP
 182 .BI List.sort\ :\ func(list:\ @[T],\ by\ =\ T.compare\ ->\ Void)
 183 Sorts the elements of the list in place in ascending order (small to large). 
 184 
 185 For more, see:
 186 .BR Tomo-List.sort (3)
 187 
 188 
 189 .TP
 190 .BI List.sorted\ :\ func(list:\ [T],\ by\ =\ T.compare\ ->\ [T])
 191 Creates a new list with elements sorted. 
 192 
 193 For more, see:
 194 .BR Tomo-List.sorted (3)
 195 
 196 
 197 .TP
 198 .BI List.to\ :\ func(list:\ [T],\ last:\ Int\ ->\ [T])
 199 Returns a slice of the list from the start of the original list up to a specified index (inclusive). 
 200 
 201 For more, see:
 202 .BR Tomo-List.to (3)
 203 
 204 
 205 .TP
 206 .BI List.unique\ :\ func(list:\ [T]\ ->\ {T})
 207 Returns a set of the unique elements of the list. 
 208 
 209 For more, see:
 210 .BR Tomo-List.unique (3)
 211 
 212 
 213 .TP
 214 .BI List.where\ :\ func(list:\ [T],\ predicate:\ func(item:&T\ ->\ Bool)\ ->\ Int)
 215 Find the index of the first item that matches a predicate function (if any). 
 216 
 217 For more, see:
 218 .BR Tomo-List.where (3)
 219