'\" t
.\" Copyright (c) 2025 Bruce Hill
.\" All rights reserved.
.\"
.TH List.sample 3 2025-09-06 "Tomo man-pages"
.SH NAME
List.sample \- weighted random choices
.SH LIBRARY
Tomo Standard Library
.SH SYNOPSIS
.nf
.BI List.sample\ :\ func(list:\ [T],\ count:\ Int,\ weights:\ [Num]?\ =\ none,\ random:\ func(->Num)?\ =\ none\ ->\ [T])
.fi
.SH DESCRIPTION
Selects a sample of elements from the list, optionally with weighted probabilities.


.SH ARGUMENTS

.TS
allbox;
lb lb lbx lb
l l l l.
Name	Type	Description	Default
list	[T]	The list to sample from. 	-
count	Int	The number of elements to sample. 	-
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
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 `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic pseudorandom number generation) 	none
.TE
.SH RETURN
A list of sampled elements from the list.

.SH ERRORS
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).

.SH EXAMPLES
.EX
>> [10, 20, 30].sample(2, weights=[90%, 5%, 5%])
= [10, 10]
.EE