Data.CircularList

A simple purely functional circular list, or ring, data type.

Lets describe what we mean by ring. A ring is a circular data structure such that if you continue rotating the ring, you'll eventually return to the element you first observed.

All of our analogies involve sitting at a table who's top surface rotates about its center axis (think of those convenient rotating platforms one often finds in an (Americanized) Chinese Restaurant).

Only the closest item on the table is avialable to us. In order to reach other elements on the table, we need to rotate the table to the left or the right.

Our convention for this problem says that rotations to the right are a forward motion while rotations to the left are backward motions.

We'll use the following circular list for our examples:

  8 7 6
 9     5
A       4
B       3
 C     2
  D 0 1
    ^

The pointer at the bottom represents our position at the table. The element currently in front of is is referred to as the focus. So, in this case, our focus is 0.

If we were to rotate the table to the right using the rotR operation, we'd have the following table.

  9 8 7
 A     6
B       5
C       4
 D     3
  0 1 2
    ^

This yields 1 as our new focus. Rotating this table left would return 0 to the focus position.

Data Types

data CList a

A functional ring type.

Instances

Functor CList

Foldable CList

Traversable CList

Eq a => Eq (CList a)

Read a => Read (CList a)

Show a => Show (CList a)

Arbitrary a => Arbitrary (CList a)

NFData a => NFData (CList a)

Functions

Creation of CLists

empty :: CList a

An empty CList.

fromList :: [a] -> CList a

Make a (balanced) CList from a list.

singleton :: a -> CList a

Update of CList

update :: a -> CList a -> CList a

Replaces the current focus with a new focus.

reverseDirection :: CList a -> CList a

Reverse the direction of rotation.

Converting CLists to Lists

leftElements :: CList a -> [a]

Starting with the focus, go left and accumulate all elements of the CList in a list.

rightElements :: CList a -> [a]

Starting with the focus, go right and accumulate all elements of the CList in a list.

toList :: CList a -> [a]

Make a list from a CList.

toInfList :: CList a -> [a]

Make a CList into an infinite list.

Extraction and Accumulation

focus :: CList a -> Maybe a

Return the focus of the CList.

insertL :: a -> CList a -> CList a

Insert an element into the CList as the new focus. The old focus is now the next element to the left.

insertR :: a -> CList a -> CList a

Insert an element into the CList as the new focus. The old focus is now the next element to the right.

removeL :: CList a -> CList a

Remove the focus from the CList. The new focus is the next element to the left.

removeR :: CList a -> CList a

Remove the focus from the CList.

Manipulation of Focus

allRotations :: CList a -> CList (CList a)

Return all possible rotations of the provided CList, where the focus is the provided CList.

rotR :: CList a -> CList a

Rotate the focus to the next (right) element.

rotL :: CList a -> CList a

Rotate the focus to the previous (left) element.

rotN :: Int -> CList a -> CList a

Rotate the focus the specified number of times; if the index is positive then it is rotated to the right; otherwise it is rotated to the left.

rotNR :: Int -> CList a -> CList a

A wrapper around rotN that doesn't rotate the CList if n <= 0.

rotNL :: Int -> CList a -> CList a

Rotate the focus the specified number of times to the left (but don't rotate if n <= 0).

rotateTo :: Eq a => a -> CList a -> Maybe (CList a)

Rotate the CList such that the specified element (if it exists) is focused.

findRotateTo :: (a -> Bool) -> CList a -> Maybe (CList a)

Attempt to rotate the CList such that focused element matches the supplied predicate.

List-like functions

filterR :: (a -> Bool) -> CList a -> CList a

Remove those elements that do not satisfy the supplied predicate, rotating to the right if the focus does not satisfy the predicate.

filterL :: (a -> Bool) -> CList a -> CList a

As with filterR, but rotates to the left if the focus does not satisfy the predicate.

foldrR :: (a -> b -> b) -> b -> CList a -> b

A right-fold, rotating to the right through the CList.

foldrL :: (a -> b -> b) -> b -> CList a -> b

A right-fold, rotating to the left through the CList.

foldlR :: (a -> b -> a) -> a -> CList b -> a

A (strict) left-fold, rotating to the right through the CList.

foldlL :: (a -> b -> a) -> a -> CList b -> a

A (strict) left-fold, rotating to the left through the CList.

Manipulation of Packing

balance :: CList a -> CList a

Balance the CList. Equivalent to `fromList . toList`

packL :: CList a -> CList a

Move all elements to the left side of the CList.

packR :: CList a -> CList a

Move all elements to the right side of the CList.

Information

isEmpty :: CList a -> Bool

Returns true if the CList is empty.

size :: CList a -> Int

Return the size of the CList.