Skip to content

Usage examples

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

Ring class

Tip

The example Ring class can be built in few lines of code, thanks to the methods in the original form method(Seq, ...) available in the ring_seq.methods module.

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 sequence.
head_index

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

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

    Attributes:
        underlying: The wrapped sequence.
        head_index: The state of rotation, a circular index of where the sequence currently starts, default = 0
        is_reflected: The state of reflection
    """
    def __init__(self, underlying: Seq, head_index: IndexO = 0, is_reflected: bool = False):
        """Initializes the instance with the sequence and the states."""
        self.underlying = underlying
        self.head_index = head_index
        self.is_reflected = is_reflected

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

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

        Examples:
          >>> r = Ring('ABC')
          >>> r.rotate_r(1)
          >>> r.current()
          'CAB'

        Args:
          step: number of rotation steps to the right
        """
        self.head_index += step * self.__direction_multiplier()

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

        Examples:
          >>> r = Ring('ABC')
          >>> r.rotate_l(1)
          >>> r.current()
          'BCA'

        Args:
          step: number of rotation steps to the left
        """
        self.rotate_r(-step)

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

        Examples:
          >>> r = Ring('ABC')
          >>> r.reflect()
          >>> r.current()
          'ACB'
        """
        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('ABC')
          >>> r.rotate_r(1)
          >>> r.current_head()
          'C'

        Returns:
          The current head element of the sequence
        """
        return apply_o(self.underlying, self.head_index)

    def current(self) -> Seq:
        """Gets the sequence at the current rotation and reflection state.

        Examples:
          >>> r = Ring('ABC')
          >>> r.rotate_r(1)
          >>> r.current()
          'CAB'

        Returns:
          The current sequence
        """
        if self.is_reflected:
            return reflect_at(self.underlying, self.head_index)
        else:
            return start_at(self.underlying, self.head_index)

__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 
21
22
23
24
25
def __init__(self, underlying: Seq, head_index: IndexO = 0, is_reflected: bool = False):
    """Initializes the instance with the sequence and the states."""
    self.underlying = underlying
    self.head_index = head_index
    self.is_reflected = is_reflected

current()

Gets the sequence at the current rotation and reflection state.

Examples:

>>> r = Ring('ABC')
>>> r.rotate_r(1)
>>> r.current()
'CAB'

Returns:

Type Description
Seq

The current sequence
Source code in src/ring_seq/examples/Ring.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def current(self) -> Seq:
    """Gets the sequence at the current rotation and reflection state.

    Examples:
      >>> r = Ring('ABC')
      >>> r.rotate_r(1)
      >>> r.current()
      'CAB'

    Returns:
      The current sequence
    """
    if self.is_reflected:
        return reflect_at(self.underlying, self.head_index)
    else:
        return start_at(self.underlying, self.head_index)

current_head()

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

Examples:

>>> r = Ring('ABC')
>>> r.rotate_r(1)
>>> r.current_head()
'C'

Returns:

Type Description
Any

The current head element of the sequence
Source code in src/ring_seq/examples/Ring.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
def current_head(self) -> Any:
    """Gets the start of the sequence at the current rotation state.

    Examples:
      >>> r = Ring('ABC')
      >>> r.rotate_r(1)
      >>> r.current_head()
      'C'

    Returns:
      The current head element of the sequence
    """
    return apply_o(self.underlying, self.head_index)

reflect()

Inverts the reflection state.

Examples:

>>> r = Ring('ABC')
>>> r.reflect()
>>> r.current()
'ACB'
Source code in src/ring_seq/examples/Ring.py 
61
62
63
64
65
66
67
68
69
70
def reflect(self):
    """Inverts the reflection state.

    Examples:
      >>> r = Ring('ABC')
      >>> r.reflect()
      >>> r.current()
      'ACB'
    """
    self.is_reflected = not self.is_reflected

rotate_l(step=1)

Updates the rotation state by some steps to the left.

Examples:

>>> r = Ring('ABC')
>>> r.rotate_l(1)
>>> r.current()
'BCA'

Parameters:

Name Type Description Default
step int

number of rotation steps to the left

 1
Source code in src/ring_seq/examples/Ring.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
def rotate_l(self, step: int = 1):
    """Updates the rotation state by some steps to the left.

    Examples:
      >>> r = Ring('ABC')
      >>> r.rotate_l(1)
      >>> r.current()
      'BCA'

    Args:
      step: number of rotation steps to the left
    """
    self.rotate_r(-step)

rotate_r(step=1)

Updates the rotation state by some steps to the right.

Examples:

>>> r = Ring('ABC')
>>> r.rotate_r(1)
>>> r.current()
'CAB'

Parameters:

Name Type Description Default
step int

number of rotation steps to the right

 1
Source code in src/ring_seq/examples/Ring.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
def rotate_r(self, step: int = 1):
    """Updates the rotation state by some steps to the right.

    Examples:
      >>> r = Ring('ABC')
      >>> r.rotate_r(1)
      >>> r.current()
      'CAB'

    Args:
      step: number of rotation steps to the right
    """
    self.head_index += step * self.__direction_multiplier()