Skip to main content

A collection of cyclic sequence objects.

Project description

Cyclic-Sequences
################

Sequence type objects with cyclic indexing::

Description
===========

The cyclic indexation works as for usual sequences, with the possible use
of negative indexes. But it makes a jump-back to the beginning (or the end for
negative indexes) if the index is higher than the length of the sequence::

┌───────────────────────────┐
│ ▼
┏━│━┳━━━┳━━━┳━╍┅ ┅╍━┳━━━━━┳━━━┳━━━┓
┃ ● ┃ 0 ┃ 1 ┃ ⋅⋅⋅ ┃ N-1 ┃ N ┃ ● ┃
┗━━━┻━━━┻━━━┻━╍┅ ┅╍━┻━━━━━┻━━━┻━│━┛
▲ │
└───────────────────────────┘

Iterating over a cyclic sequence is bounded (no infinite loop).


.. note:: This module is based on a Chris Lawlor forum publication.


Content
=======

:CyclicTuple:
Class object.
An immutable cyclic sequence based on built-in class *tuple*.

:CyclicList:
Class object.
A mutable cyclic sequence based on built-in class *list*.

:CyclicStr:
Class object.
An immutable cyclic sequence based on built-in class *str*.


Immutable class methods
-----------------------

:with_first:
foo.with_first(elt) -> new instance
New instance of 'foo' with first occurence of 'elt' at first position.
Raises ValueError if 'elt' is not present.

:turned:
foo.turned(step) -> new instance
New instance of 'foo' with all elements shifted of given step.
(default is 1 unit onward).


Mutable class methods
---------------------

:set_first:
foo.set_first(elt) -> None
Set first occurence of 'elt' at first position.
Raises ValueError if 'elt' is not present.

:turn:
foo.turn(step) -> None
Change all elements indexes of given step (default is 1 unit onward)
Equivalent to set at first position the element at index 'step'.


Examples
========

The following examples are using CyclicList class for demonstration. CyclicTuple and CyclicStr classes get similar behaviours.

- Construction from any iterable::

>>> foo = CyclicList(['a', 'b', 'c', 'd', 'e'])
>>> foo
CyclicList(['a', 'b', 'c', 'd', 'e'])

- Gets its specific string representation with chevrons figuring cycling::

>>> print(foo)
<['a', 'b', 'c', 'd', 'e']>

- Accessing works like a regular list::

>>> foo[1]
'b'
>>> foo[-4]
'b'

- Except indexes higher than length wraps around::

>>> foo[6]
'b'
>>> foo[11]
'b'
>>> foo[-9]
'b'

- Slices work and return list objects::

>>> foo[1:4]
['b', 'c', 'd']
>>> foo[3:0:-1]
['d', 'c', 'b']

- Slices work also out of range with cyclic output::

>>> foo[3:7]
['d', 'e', 'a', 'b']
>>> foo[8:12]
['d', 'e', 'a', 'b']
>>> foo[3:12]
['d', 'e', 'a', 'b', 'c', 'd', 'e', 'a', 'b']
>>> foo[-2:2]
['d', 'e', 'a', 'b']
>>> foo[-7:-3]
['d', 'e', 'a', 'b']
>>> foo[-7:2]
['d', 'e', 'a', 'b', 'c', 'd', 'e', 'a', 'b']

- Slices with non unitary steps work also::

>>> foo[:7:2]
['a', 'c', 'e', 'b']
>>> foo[:7:3]
['a', 'd', 'b']
>>> foo[:7:5]
['a', 'a']

- As well for reversed steps::

>>> foo[1:-3:-1]
['b', 'a', 'e', 'd']
>>> foo[-4:-8:-1]
['b', 'a', 'e', 'd']
>>> foo[-4:-9:-2]
['b', 'e', 'c']
>>> foo[-4:-9:-3]
['b', 'd']
>>> foo[-5:-11:-5]
['a', 'a']

- Incoherent slices return empty list::

>>> foo[11:5]
[]

Edge effects:

- Indexing an empty CyclicList returns an IndexError.

- Indexing on a unique element returns always this element.


First element can be played with using specific methods:

- **with_first**: return a new CyclicList with given element at first
position::

>>> foo.with_first('c')
CyclicList(['c', 'd', 'e', 'a', 'b'])

- **turned**: return a new CyclicList with all elements indexes changed
of given step (default is 1 unit onward)::

>>> foo.turned()
CyclicList(['b', 'c', 'd', 'e', 'a'])
>>> foo.turned(-3)
CyclicList(['c', 'd', 'e', 'a', 'b'])
>>> foo.turned(10)
CyclicList(['a', 'b', 'c', 'd', 'e'])

- **set_first**: put given element at first position::

>>> foo.set_first('c')
>>> foo
CyclicList(['c', 'd', 'e', 'a', 'b'])

- **turn**: change all elements index of given step
(default is 1 unit onward)::

>>> foo.turn()
>>> foo
CyclicList(['d', 'e', 'a', 'b', 'c'])
>>> foo.turn(-3)
>>> foo
CyclicList(['a', 'b', 'c', 'd', 'e'])
>>> foo.turn(11)
>>> foo
CyclicList(['b', 'c', 'd', 'e', 'a'])


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cyclic-sequences, version 1.1.2
Filename, size File type Python version Upload date Hashes
Filename, size cyclic_sequences-1.1.2-py3-none-any.whl (8.9 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page