tomo-List.sample.3

(41 lines)
   1 '\" t
   2 .\" Copyright (c) 2026 Bruce Hill
   3 .\" All rights reserved.
   4 .\"
   5 .TH List.sample 3 2026-03-08 "Tomo man-pages"
   6 .SH NAME
   7 List.sample \- weighted random choices
   8 .SH LIBRARY
   9 Tomo Standard Library
  10 .SH SYNOPSIS
  11 .nf
  12 .BI List.sample\ :\ func(list:\ [T],\ count:\ Int,\ weights:\ [Num]?\ =\ none,\ random:\ func(->Num)?\ =\ none\ ->\ [T])
  13 .fi
  14 .SH DESCRIPTION
  15 Selects a sample of elements from the list, optionally with weighted probabilities.
  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 list to sample from. 	-
  26 count	Int	The number of elements to sample. 	-
  27 weights	[Num]?	The probability weights for each element in the list. These values do not need to add up to any particular number, they are relative weights. If no weights are given, elements will be sampled with uniform probability. 	none
  28 random	func(->Num)?	If provided, this function will be used to get random values for sampling the list. The provided function should return random numbers between \fB0.0\fR (inclusive) and \fB1.0\fR (exclusive). (Used for deterministic pseudorandom number generation) 	none
  29 .TE
  30 .SH RETURN
  31 A list of sampled elements from the list.
  32 
  33 .SH ERRORS
  34 Errors will be raised if any of the following conditions occurs: - The given list has no elements and `count >= 1` - `count < 0` (negative count) - The number of weights provided doesn't match the length of the list.  - Any weight in the weights list is negative, infinite, or `NaN` - The sum of the given weights is zero (zero probability for every element).
  35 
  36 .SH EXAMPLES
  37 .EX
  38 _ := [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) # E.g. [10, 10]
  39 .EE
  40 .SH SEE ALSO
  41 .BR Tomo-List (3)