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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
use num::basic::integers::PrimitiveInt;
use num::logic::traits::{BitConvertible, NotAssign};
use std::fmt::Debug;

const COUNTER_WIDTH: usize = u64::WIDTH as usize;

/// This struct is used to configure [`BitDistributor`]s.
///
/// See the [`BitDistributor`] documentation for more.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct BitDistributorOutputType {
    weight: usize, // 0 means a tiny output_type
    max_bits: Option<usize>,
}

impl BitDistributorOutputType {
    /// Creates a normal output with a specified weight.
    ///
    /// # Worst-case complexity
    /// Constant time and additional memory.
    ///
    /// # Panics
    /// Panics if `weight` is zero.
    ///
    /// The corresponding element grows as a power of $i$. See the [`BitDistributor`] documentation
    /// for more.
    pub fn normal(weight: usize) -> BitDistributorOutputType {
        assert_ne!(weight, 0);
        BitDistributorOutputType {
            weight,
            max_bits: None,
        }
    }

    /// Creates a tiny output.
    ///
    /// # Worst-case complexity
    /// Constant time and additional memory.
    ///
    /// The corresponding element grows logarithmically. See the [`BitDistributor`] documentation
    /// for more.
    pub const fn tiny() -> BitDistributorOutputType {
        BitDistributorOutputType {
            weight: 0,
            max_bits: None,
        }
    }
}

/// Helps generate tuples exhaustively.
///
/// Think of `counter` as the bits of an integer. It's initialized to zero (all `false`s), and as
/// it's repeatedly incremented, it eventually takes on every 64-bit value.
///
/// `output_types` is a list of $n$ configuration structs that, together, specify how to generate an
/// n-element tuple of unsigned integers. Calling `get_output` repeatedly, passing in 0 through
/// $n - 1$ as `index`, distributes the bits of `counter` into a tuple.
///
/// This is best shown with an example. If `output_types` is set to
/// `[BitDistributorOutputType::normal(1); 2]`, the distributor will generate all pairs of unsigned
/// integers. A pair may be extracted by calling `get_output(0)` and `get_output(1)`; then `counter`
/// may be incremented to create the next pair. In this case, the pairs will be
/// $(0, 0), (0, 1), (1, 0), (1, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 0), (2, 1), \ldots$.
///
/// If you think of these pairs as coordinates in the $xy$-plane, they are traversed along a
/// [Z-order curve](https://en.wikipedia.org/wiki/Z-order_curve). Every pair of unsigned integers
/// will be generated exactly once.
///
/// In general, setting `output_types` to `[BitDistributorOutputType::normal(1); n]` will generate
/// $n$-tuples. The elements of the tuples will be very roughly the same size, in the sense that
/// each element will grow as $O(\sqrt\[n\]{i})$, where $i$ is the counter. Sometimes we want the
/// elements to grow at different rates. To accomplish this, we can change the weights of the output
/// types. For example, if we set `output_types` to
/// `[BitDistributorOutputType::normal(1), BitDistributorOutputType::normal(2)]`, the first element
/// of the generated pairs will grow as $O(\sqrt\[3\]{i})$ and the second as $O(i^{2/3})$. In
/// general, if the weights are $w_0, w_1, \\ldots, w_{n-1}$, then the $k$th element of the output
/// tuples will grow as $O(i^{w_i/\sum_{j=0}^{n-1}w_j})$.
///
/// Apart from creating _normal_ output types with different weights, we can create _tiny_ output
/// types, which indicate that the corresponding tuple element should grow especially slowly. If
/// `output_types` contains $m$ tiny output types, each tiny tuple element grows as
/// $O(\sqrt\[m\]{\log i})$. The growth of the other elements is unaffected. Having only tiny types
/// in `output_types` is disallowed.
///
/// The above discussion of growth rates assumes that `max_bits` is not specified for any output
/// type. But if `max_bits` is set to $b$, then the corresponding element will start growing just as
/// if `max_bits` wasn't specified, but will stop growing once it reaches $2^b-1$.
#[derive(Clone, Debug, Eq, PartialEq, Hash)]
pub struct BitDistributor {
    #[cfg(feature = "test_build")]
    pub output_types: Vec<BitDistributorOutputType>,
    #[cfg(not(feature = "test_build"))]
    output_types: Vec<BitDistributorOutputType>,
    bit_map: [usize; COUNTER_WIDTH],
    counter: [bool; COUNTER_WIDTH],
}

impl BitDistributor {
    fn new_without_init(output_types: &[BitDistributorOutputType]) -> BitDistributor {
        if output_types
            .iter()
            .all(|output_type| output_type.weight == 0)
        {
            panic!("All output_types cannot be tiny");
        }
        BitDistributor {
            output_types: output_types.to_vec(),
            bit_map: [0; COUNTER_WIDTH],
            counter: [false; COUNTER_WIDTH],
        }
    }

    /// Creates a new [`BitDistributor`].
    ///
    /// # Worst-case complexity
    /// $T(n) = O(n)$
    ///
    /// $M(n) = O(n)$
    ///
    /// where $T$ is time, $M$ is additional memory, and $n$ is `output_types.len()`.
    ///
    /// # Examples
    /// ```
    /// use malachite_base::iterators::bit_distributor::{BitDistributor, BitDistributorOutputType};
    ///
    /// BitDistributor::new(
    ///     &[BitDistributorOutputType::normal(2), BitDistributorOutputType::tiny()]
    /// );
    /// ```
    pub fn new(output_types: &[BitDistributorOutputType]) -> BitDistributor {
        let mut distributor = BitDistributor::new_without_init(output_types);
        distributor.update_bit_map();
        distributor
    }

    /// Returns a reference to the internal bit map as a slice.
    ///
    /// The bit map determines which output gets each bit of the counter. For example, if the bit
    /// map is $[0, 1, 0, 1, 0, 1, \ldots]$, then the first element of the output pair gets the bits
    /// with indices $0, 2, 4, \ldots$ and the second element gets the bits with indices
    /// $1, 3, 5, \ldots$.
    ///
    /// # Worst-case complexity
    /// Constant time and additional memory.
    ///
    /// # Examples
    /// ```
    /// use malachite_base::iterators::bit_distributor::{BitDistributor, BitDistributorOutputType};
    ///
    /// let bd = BitDistributor::new(&[
    ///     BitDistributorOutputType::normal(2),
    ///     BitDistributorOutputType::tiny(),
    /// ]);
    /// assert_eq!(
    ///     bd.bit_map_as_slice(),
    ///     &[
    ///         1, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    ///         0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    ///         0, 0, 0, 0, 0, 0, 0, 1
    ///     ][..]
    /// );
    /// ```
    pub fn bit_map_as_slice(&self) -> &[usize] {
        self.bit_map.as_ref()
    }

    fn update_bit_map(&mut self) {
        let (mut normal_output_type_indices, mut tiny_output_type_indices): (
            Vec<usize>,
            Vec<usize>,
        ) = (0..self.output_types.len()).partition(|&i| self.output_types[i].weight != 0);
        let mut normal_output_types_bits_used = vec![0; normal_output_type_indices.len()];
        let mut tiny_output_types_bits_used = vec![0; tiny_output_type_indices.len()];
        let mut ni = normal_output_type_indices.len() - 1;
        let mut ti = tiny_output_type_indices.len().saturating_sub(1);
        let mut weight_counter = self.output_types[normal_output_type_indices[ni]].weight;
        for i in 0..COUNTER_WIDTH {
            let use_normal_output_type = !normal_output_type_indices.is_empty()
                && (tiny_output_type_indices.is_empty() || !usize::is_power_of_two(i + 1));
            if use_normal_output_type {
                self.bit_map[i] = normal_output_type_indices[ni];
                let output_type = self.output_types[normal_output_type_indices[ni]];
                normal_output_types_bits_used[ni] += 1;
                weight_counter -= 1;
                if output_type.max_bits == Some(normal_output_types_bits_used[ni]) {
                    normal_output_type_indices.remove(ni);
                    normal_output_types_bits_used.remove(ni);
                    if normal_output_type_indices.is_empty() {
                        continue;
                    }
                    weight_counter = 0;
                }
                if weight_counter == 0 {
                    if ni == 0 {
                        ni = normal_output_type_indices.len() - 1;
                    } else {
                        ni -= 1;
                    }
                    weight_counter = self.output_types[normal_output_type_indices[ni]].weight;
                }
            } else {
                if tiny_output_type_indices.is_empty() {
                    self.bit_map[i] = usize::MAX;
                    continue;
                }
                self.bit_map[i] = tiny_output_type_indices[ti];
                let output_type = self.output_types[tiny_output_type_indices[ti]];
                tiny_output_types_bits_used[ti] += 1;
                if output_type.max_bits == Some(tiny_output_types_bits_used[ti]) {
                    tiny_output_type_indices.remove(ti);
                    tiny_output_types_bits_used.remove(ti);
                    if tiny_output_type_indices.is_empty() {
                        continue;
                    }
                }
                if ti == 0 {
                    ti = tiny_output_type_indices.len() - 1;
                } else {
                    ti -= 1;
                }
            }
        }
    }

    /// Sets the maximum bits for several outputs.
    ///
    /// Given slice of output indices, sets the maximum bits for each of the outputs and rebuilds
    /// the bit map.
    ///
    /// # Worst-case complexity
    /// $T(n) = O(n)$
    ///
    /// $M(n) = O(1)$
    ///
    /// where $T$ is time, $M$ is additional memory, and $n$ is `output_type_indices.len()`.
    ///
    /// # Panics
    /// Panics if `max_bits` is 0 or if any index is greater than or equal to
    /// `self.output_types.len()`.
    ///
    /// # Examples
    /// ```
    /// use malachite_base::iterators::bit_distributor::{BitDistributor, BitDistributorOutputType};
    ///
    /// let mut bd = BitDistributor::new(&[BitDistributorOutputType::normal(2); 3]);
    /// assert_eq!(
    ///     bd.bit_map_as_slice(),
    ///     &[
    ///         2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 1, 1,
    ///         0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 2,
    ///         1, 1, 0, 0, 2, 2, 1, 1
    ///     ][..]
    /// );
    ///
    /// bd.set_max_bits(&[0, 2], 5);
    /// assert_eq!(
    ///     bd.bit_map_as_slice(),
    ///     &[
    ///         2, 2, 1, 1, 0, 0, 2, 2, 1, 1, 0, 0, 2, 1, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
    ///         1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
    ///         1, 1, 1, 1, 1, 1, 1, 1
    ///     ][..]
    /// );
    /// ```
    pub fn set_max_bits(&mut self, output_type_indices: &[usize], max_bits: usize) {
        assert_ne!(max_bits, 0);
        for &index in output_type_indices {
            self.output_types[index].max_bits = Some(max_bits);
        }
        self.update_bit_map();
    }

    /// Increments the counter in preparation for a new set of outputs.
    ///
    /// If the counter is incremented $2^{64}$ times, it rolls back to 0.
    ///
    /// # Worst-case complexity
    /// Constant time and additional memory.
    ///
    /// # Examples
    /// ```
    /// use malachite_base::iterators::bit_distributor::{BitDistributor, BitDistributorOutputType};
    ///
    /// let mut bd = BitDistributor::new(&[BitDistributorOutputType::normal(1)]);
    /// let mut outputs = Vec::new();
    /// for _ in 0..20 {
    ///     outputs.push(bd.get_output(0));
    ///     bd.increment_counter();
    /// }
    /// assert_eq!(
    ///     outputs,
    ///     &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
    /// );
    /// ```
    pub fn increment_counter(&mut self) {
        for b in self.counter.iter_mut() {
            b.not_assign();
            if *b {
                break;
            }
        }
    }

    /// Gets the output at a specified index.
    ///
    /// # Worst-case complexity
    /// Constant time and additional memory.
    ///
    /// # Panics
    /// Panics if `index` is greater than or equal to `self.output_types.len()`.
    ///
    /// # Examples
    /// ```
    /// extern crate itertools;
    ///
    /// use itertools::Itertools;
    /// use malachite_base::iterators::bit_distributor::{BitDistributor, BitDistributorOutputType};
    ///
    /// let mut bd = BitDistributor::new(&[BitDistributorOutputType::normal(1); 2]);
    /// let mut outputs = Vec::new();
    /// for _ in 0..10 {
    ///     outputs.push((0..2).map(|i| bd.get_output(i)).collect_vec());
    ///     bd.increment_counter();
    /// }
    /// let expected_outputs: &[&[usize]] = &[
    ///     &[0, 0], &[0, 1], &[1, 0], &[1, 1], &[0, 2], &[0, 3], &[1, 2], &[1, 3], &[2, 0], &[2, 1]
    /// ];
    /// assert_eq!(outputs, expected_outputs);
    /// ```
    pub fn get_output(&self, index: usize) -> usize {
        assert!(index < self.output_types.len());
        usize::from_bits_asc(
            self.bit_map
                .iter()
                .zip(self.counter.iter())
                .filter_map(|(&m, &c)| if m == index { Some(c) } else { None }),
        )
    }
}