ENH: shuffled released

Author: hoxnox

README.md

@@ -26,6 +26,7 @@ evaluation wherever possible.
 [accumulate](#accumulate)<br />
 [compress](#compress)<br />
 [sorted](#sorted)<br />
+[shuffled](#shuffled)<br />
 [chain](#chain)<br />
 [chain.from\_iterable](#chainfrom_iterable)<br />
 [reversed](#reversed)<br />
@@ -525,6 +526,25 @@ an `operator*() const` member.
 
 The below outputs `0 1 2 3 4`.
 
+```c++
+unordered_set<int> nums{4, 0, 2, 1, 3};
+for (auto&& i : sorted(nums)) {
+    cout << i << ' ';
+}
+```
+
+shuffled
+--------
+*Additional Requirements*: Input must have a ForwardIterator.
+
+Allows iteration over a sequence in shuffled order. `shuffled` does
+**not** produce a new sequence, copy elements, or modify the original
+sequence.  It only provides a way to iterate over existing elements.
+`shuffled` also takes an optional second argument - randomization seed.
+If not provided, defaults to 1.
+
+The below outputs `0 2 4 3 1`.
+
 ```c++
 unordered_set<int> nums{4, 0, 2, 1, 3};
 for (auto&& i : sorted(nums)) {

shuffled.hpp

@@ -0,0 +1,185 @@
+#ifndef ITER_SHUFFLED_HPP_
+#define ITER_SHUFFLED_HPP_
+
+#include "internal/iterbase.hpp"
+
+/* Suppose the size of the container is N. We can find the power of two,
+ * that is greater or equal to N - K. Numbers from 1 to K can be easy
+ * shuffled with help of Linear Feedback Shift Register (LFSR) using
+ * special prime poly. Access to every element of the shuffled is
+ * implemented through advance of the first (begin) iterator of the
+ * container, so random access iterator is desirable. In the constructor
+ * we have to calculate the total size of the container, so
+ * dumb_distance will be used.*/
+
+namespace iter {
+  namespace impl {
+    template <typename Container, typename Distance = std::size_t>
+    class ShuffledView;
+    // linear feedback shift register
+    namespace lfsr {
+      const uint16_t PRIME_POLY[64] = {
+        1, 3, 3, 3, 5, 3, 3, 29, 17, 9, 5, 83, 27, 43, 3, 45, 9, 129, 39,
+        9, 5, 3, 33, 27, 9, 71, 39, 9, 5, 83, 9, 197, 8193, 231, 5, 119,
+        83, 99, 17, 57, 9, 153, 89, 101, 27, 449, 33, 183, 113, 29, 75,
+        9, 71, 125, 71, 149, 129, 99, 123, 3, 39, 105, 3, 27
+      }; // prime poly for full-cycle shift registers
+      uint16_t get_approx(uint64_t val);
+      uint64_t shift(uint64_t reg, uint8_t reg_size);
+    }
+  }
+
+  template <typename Container, typename Distance = std::size_t>
+  impl::ShuffledView<Container, Distance> shuffled(Container&&, int seed = 1);
+}
+
+// power of 2 approximation
+uint16_t iter::impl::lfsr::get_approx(uint64_t val) {
+  if (val == 0)
+	  return 0;
+  uint16_t pow2_approx = 0;
+  if (val > 9223372036854775808UL) {
+    pow2_approx = 63;
+  }
+  else {
+    while (pow2_approx < 64) {
+      if (val >= (1UL << (pow2_approx + 1)))
+        ++pow2_approx;
+      else
+        break;
+    }
+  }
+  return pow2_approx + 1;
+}
+
+uint64_t iter::impl::lfsr::shift(uint64_t reg, uint8_t reg_size) {
+  if (reg & 1)
+    reg = ((reg ^ PRIME_POLY[reg_size]) >> 1) | (1 << reg_size);
+  else
+    reg >>= 1;
+  return reg;
+}
+
+template <typename Container, typename Distance>
+class iter::impl::ShuffledView {
+ private:
+
+  Distance                 size;
+  uint8_t                  size_approx;
+  iterator_type<Container> in_begin;
+  uint64_t                 seed;
+
+  template <typename C, typename D>
+  friend ShuffledView<C, D> iter::shuffled(C&&, int);
+
+
+ public:
+  using IterDeref = typename std::remove_reference<iterator_deref<Container>>;
+  ShuffledView(ShuffledView&&) : size(0) {};
+  ShuffledView(Container&& container, int seed)
+      : size(dumb_size(container)), size_approx(lfsr::get_approx(size)),
+        in_begin(std::begin(container)), seed(seed) {
+    if (size > 0)
+    {
+      uint64_t mask = 0;
+      std::uninitialized_fill((char*)&mask, (char*)&mask + size_approx, 0xFF);
+      this->seed = seed & mask;
+      this->seed = lfsr::shift(this->seed, size_approx);
+      while(this->seed >= size)
+        this->seed = lfsr::shift(this->seed, size_approx);
+    }
+  }
+
+  class Iterator
+      : public std::iterator<std::input_iterator_tag, IterDeref> {
+  private:
+    friend class ShuffledView<Container, Distance>;
+    ShuffledView<Container, Distance>* owner;
+    uint64_t state;
+    iterator_type<Container> copy; // referenced by operator* value
+
+  public:
+    Iterator() : owner(nullptr), state(0) {}
+    Iterator& operator=(const Iterator& other) {
+      owner = other.owner;
+      state = other.state;
+      return *this;
+    };
+
+    Iterator& operator++() {
+      if (operator==(owner->end()))
+        return *this;
+      state = lfsr::shift(state, owner->size_approx);
+      while(state > owner->size)
+        state = lfsr::shift(state, owner->size_approx);
+      if (state == owner->seed)
+        operator=(owner->end());
+      return *this;
+    }
+
+    Iterator operator++(int) {
+      auto ret = *this;
+      ++*this;
+      return ret;
+    }
+
+    bool operator==(const Iterator& other) const {
+      return  owner == other.owner && state == other.state;
+    }
+
+    bool operator!=(const Iterator& other) const {
+      return !operator==(other);
+    }
+
+    auto operator*() -> decltype(*copy) {
+      copy = owner->in_begin;
+      dumb_advance(copy, static_cast<Distance>(state-1));
+      return *copy;
+    }
+
+    ArrowProxy<IterDeref> operator->() {
+      return {**this};
+    }
+  };
+
+  Iterator begin() {
+    Iterator begin;
+    begin.owner = this;
+    begin.state = (size == 0 ? 0 : seed);
+    return begin;
+  }
+
+  Iterator end() {
+    Iterator end;
+    end.owner = this;
+    end.state = 0;
+    return end;
+  }
+
+  /* @brief restore iteration through a vector in shuffled order from the
+   * index of the last seen element in non shuffled container
+   *
+   * @example:
+   *   v = {"apple", "banana", "orange", "peach"}; // original vector
+   *   s = shuffled(v); // {"orange", "peach", "banana", "apple"} - shuffled vector
+   *
+   *   We iterated through s. Last seen element was "banana". In the
+   *   original vector "banana" had index 1. So to restore shuffling wee
+   *   need to do s.restore(1); Operation is zero cost - no iterators
+   *   advance is needed.*/
+  Iterator restore(uint64_t state) {
+    Iterator rs;
+    rs.owner = this;
+    rs.state = (state >= size ? seed : state + 1);
+    return rs;
+  }
+};
+
+template <typename Container, typename Distance = std::size_t>
+iter::impl::ShuffledView<Container, Distance> iter::shuffled(
+    Container&& container, int seed = 1) {
+  return {std::forward<Container>(container), seed};
+}
+
+#endif
+

test/SConstruct

@@ -36,6 +36,7 @@ progs = Split(
     slice
     sliding_window
     sorted
+    shuffled
     takewhile
     unique_everseen
     unique_justseen