Skip to content

Usage examples

This page shows examples of how the library can be used.

Ring class

Tip

The example Ring class demonstrates how a mutable ring view can be built on top of the immutable RingSeq class — keeping separate rotation and reflection states, then combining them to reproduce the current orientation.

ring_seq.examples.Ring.Ring

An example class wrapping a sequence and keeping mutable states of rotation and reflection.

Attributes:

Name Type Description
underlying

The wrapped RingSeq.
head_index

The state of rotation, a circular index of where the sequence currently starts
is_reflected

The state of reflection
Source code in src/ring_seq/examples/Ring.py 
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
class Ring:
    """An example class wrapping a sequence and keeping mutable states of rotation and reflection.

    Attributes:
        underlying: The wrapped `RingSeq`.
        head_index: The state of rotation, a circular index of where the sequence currently starts
        is_reflected: The state of reflection
    """

    def __init__(self, underlying, head_index: IndexO = 0, is_reflected: bool = False):
        """Initializes the instance with the sequence and the states."""
        self._kind = type(underlying) if isinstance(underlying, (list, tuple, str)) else list
        self.underlying = RingSeq(underlying)
        self.head_index = head_index
        self.is_reflected = is_reflected

    def __direction_multiplier(self) -> int:
        return 1 if self.is_reflected else -1

    def rotate_r(self, step: int = 1) -> None:
        """Updates the rotation state by some steps to the right.

        Examples:
          >>> r = Ring([1, 2, 3])
          >>> r.rotate_r(1)
          >>> r.current()
          [3, 1, 2]
        """
        self.head_index += step * self.__direction_multiplier()

    def rotate_l(self, step: int = 1) -> None:
        """Updates the rotation state by some steps to the left.

        Examples:
          >>> r = Ring([1, 2, 3])
          >>> r.rotate_l(1)
          >>> r.current()
          [2, 3, 1]
        """
        self.rotate_r(-step)

    def reflect(self) -> None:
        """Inverts the reflection state.

        Examples:
          >>> r = Ring([1, 2, 3])
          >>> r.reflect()
          >>> r.current()
          [1, 3, 2]
        """
        self.is_reflected = not self.is_reflected

    def current_head(self) -> Any:
        """Gets the start of the sequence at the current rotation state.

        Examples:
          >>> r = Ring([1, 2, 3])
          >>> r.rotate_r(1)
          >>> r.current_head()
          3
        """
        return self.underlying[self.head_index]

    def current(self):
        """Gets the sequence at the current rotation and reflection state,
        in the same concrete type as the original input.
        """
        ring = (
            self.underlying.reflect_at(self.head_index)
            if self.is_reflected
            else self.underlying.start_at(self.head_index)
        )
        if self._kind is str:
            return ring.to_str()
        if self._kind is tuple:
            return ring.to_tuple()
        return ring.to_list()

__init__(underlying, head_index=0, is_reflected=False)

Initializes the instance with the sequence and the states.

Source code in src/ring_seq/examples/Ring.py 
25
26
27
28
29
30
def __init__(self, underlying, head_index: IndexO = 0, is_reflected: bool = False):
    """Initializes the instance with the sequence and the states."""
    self._kind = type(underlying) if isinstance(underlying, (list, tuple, str)) else list
    self.underlying = RingSeq(underlying)
    self.head_index = head_index
    self.is_reflected = is_reflected

current()

Gets the sequence at the current rotation and reflection state, in the same concrete type as the original input.

Source code in src/ring_seq/examples/Ring.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def current(self):
    """Gets the sequence at the current rotation and reflection state,
    in the same concrete type as the original input.
    """
    ring = (
        self.underlying.reflect_at(self.head_index)
        if self.is_reflected
        else self.underlying.start_at(self.head_index)
    )
    if self._kind is str:
        return ring.to_str()
    if self._kind is tuple:
        return ring.to_tuple()
    return ring.to_list()

current_head()

Gets the start of the sequence at the current rotation state.

Examples:

>>> r = Ring([1, 2, 3])
>>> r.rotate_r(1)
>>> r.current_head()
3
Source code in src/ring_seq/examples/Ring.py 
68
69
70
71
72
73
74
75
76
77
def current_head(self) -> Any:
    """Gets the start of the sequence at the current rotation state.

    Examples:
      >>> r = Ring([1, 2, 3])
      >>> r.rotate_r(1)
      >>> r.current_head()
      3
    """
    return self.underlying[self.head_index]

reflect()

Inverts the reflection state.

Examples:

>>> r = Ring([1, 2, 3])
>>> r.reflect()
>>> r.current()
[1, 3, 2]
Source code in src/ring_seq/examples/Ring.py 
57
58
59
60
61
62
63
64
65
66
def reflect(self) -> None:
    """Inverts the reflection state.

    Examples:
      >>> r = Ring([1, 2, 3])
      >>> r.reflect()
      >>> r.current()
      [1, 3, 2]
    """
    self.is_reflected = not self.is_reflected

rotate_l(step=1)

Updates the rotation state by some steps to the left.

Examples:

>>> r = Ring([1, 2, 3])
>>> r.rotate_l(1)
>>> r.current()
[2, 3, 1]
Source code in src/ring_seq/examples/Ring.py 
46
47
48
49
50
51
52
53
54
55
def rotate_l(self, step: int = 1) -> None:
    """Updates the rotation state by some steps to the left.

    Examples:
      >>> r = Ring([1, 2, 3])
      >>> r.rotate_l(1)
      >>> r.current()
      [2, 3, 1]
    """
    self.rotate_r(-step)

rotate_r(step=1)

Updates the rotation state by some steps to the right.

Examples:

>>> r = Ring([1, 2, 3])
>>> r.rotate_r(1)
>>> r.current()
[3, 1, 2]
Source code in src/ring_seq/examples/Ring.py 
35
36
37
38
39
40
41
42
43
44
def rotate_r(self, step: int = 1) -> None:
    """Updates the rotation state by some steps to the right.

    Examples:
      >>> r = Ring([1, 2, 3])
      >>> r.rotate_r(1)
      >>> r.current()
      [3, 1, 2]
    """
    self.head_index += step * self.__direction_multiplier()