#!/usr/bin/env python3
+# © Copyright 2021-2022, Scott Gasch
+
+"""Some useful(?) utilities for dealing with Lists."""
+
+import random
from collections import Counter
from itertools import islice
-from typing import Any, Iterator, List, Mapping, Sequence, Tuple
+from typing import Any, Iterator, List, MutableSequence, Sequence, Tuple
def shard(lst: List[Any], size: int) -> Iterator[Any]:
yield from _permute(cdr, path + car)
-def binary_search(
- lst: Sequence[Any], target: Any, *, sanity_check=False
-) -> Tuple[bool, int]:
+def shuffle(seq: MutableSequence[Any]) -> MutableSequence[Any]:
+ """Shuffles a sequence into a random order.
+
+ >>> random.seed(22)
+ >>> shuffle([1, 2, 3, 4, 5])
+ [3, 4, 1, 5, 2]
+
+ >>> shuffle('example')
+ 'empaelx'
+
+ """
+ if isinstance(seq, str):
+ import string_utils
+
+ return string_utils.shuffle(seq)
+ else:
+ random.shuffle(seq)
+ return seq
+
+
+def scramble(seq: MutableSequence[Any]) -> MutableSequence[Any]:
+ return shuffle(seq)
+
+
+def binary_search(lst: Sequence[Any], target: Any, *, sanity_check=False) -> Tuple[bool, int]:
"""Performs a binary search on lst (which must already be sorted).
Returns a Tuple composed of a bool which indicates whether the
target was found and an int which indicates the index closest to
return _binary_search(lst, target, 0, len(lst) - 1)
-def _binary_search(
- lst: Sequence[Any], target: Any, low: int, high: int
-) -> Tuple[bool, int]:
+def _binary_search(lst: Sequence[Any], target: Any, low: int, high: int) -> Tuple[bool, int]:
if high >= low:
mid = (high + low) // 2
if lst[mid] == target: