weighted-list 0.2.0

A list class for weighted randomisation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

# weighted-list


A vector implementation for weighted randomisation.

Implements the `WeightedList` struct, an ordered collection of `WeightedItem`s, which hold a `value` and `weight`. Indexing and random selection takes the weight of items into consideration, such that items with greater weights are more likely to be selected.


## Usage


### Import

```rust
// blanket import
use weighted_list::*;

// specific imports
use weighted_list::{
    WeightedList, wlist,
    WeightedItem, wit,
};
```

### Construction

```rust
// macro
let wl = wlist![
    (2, "sup"),
    (3, "nova"),
    (5, "shard"),
];

// constructor
let wl = WeightedList::init(
    [
        (2, "sup"),
        (3, "nova"),
        (5, "shard"),
    ]
);
```

### Weighted Randomisation

```rs
let descriptors = wlist![
    (10, String::from("cool")),
    (5,  String::from("awesome")),
    (2,  String::from("elegant")),
    (1,  String::from("beautiful")),
];

// single selection
let word = descriptors.select_random_value(&mut rand::rng());

if let Some(chosen) = word {
    println!("You look {chosen}");
    // => You look cool
    //    (10/18 probability)
}

// multiple selection (bon builder syntax)
let words = descriptors.select_random_values()
    .rng(&mut rand::rng())
    .count(2)
    .unique(true)
    .call();

if let Some(first) = words[0] && let Some(second) = words[1] {
    println!("Rust is {} and {}", first, second);
    // => Rust is awesome and elegant
}
```

### Indexing

```rust
let wl = wlist![
    (1, "qi"),
    (2, "sup"),
    (5, "shard"),
];

wl[0]; // => WeightedItem { weight: 1, value: "qi" }
wl[1]; // => WeightedItem { weight: 2, value: "sup" }
wl[2]; // => WeightedItem { weight: 2, value: "sup" }
wl[3]; // => WeightedItem { weight: 5, value: "shard" }
wl[4]; // => WeightedItem { weight: 5, value: "shard" }
wl[5]; // => WeightedItem { weight: 5, value: "shard" }
wl[6]; // => WeightedItem { weight: 5, value: "shard" }
wl[7]; // => WeightedItem { weight: 5, value: "shard" }
wl[8]; // panic - out of bounds!
```