Data.NibbleString

NibbleString is the "ByteString" of nibbles (4 bit values). It is intended to be used in the same way that ByteString is used, although, currently, only a subset of the functions have been implemented.

Internally, a NibbleString stores data similarly to ByteString, however, as per design:

• Each byte of data in a NibbleString contributes 2 to the length.
• When unpacked, each byte of data in a NibbleString creates 2 Nibble items.
• Unlike a ByteString, a NibbleString can hold an odd number of Nibbles.

For the most part, NibbleString is a convenience wrapper around ByteString

Documentation

type Nibble = Word8

Nibbles are stored as the low four bits of a Word8.

Nothing prevents storing 1s in the upper four bits, but the functions here will (do their best to) ignore this data, or complain when it is set.

data NibbleString

This is the basic NibbleString data type.

A NibbleString is just a ByteString internally, but with a spot to store the extra Nibble for odd length strings.

Constructors

EvenNibbleString ByteString

OddNibbleString Nibble ByteString

Instances

Eq NibbleString

Ord NibbleString

Show NibbleString

IsString NibbleString

Pretty NibbleString

empty :: NibbleString

O(1) Returns the NibbleString of length 0.

singleton :: Nibble -> NibbleString

O(1) Creates a NibbleString of length 1 using the given Nibble.

null :: NibbleString -> Bool

O(1) Returns True if the NibbleString has size 0.

length :: NibbleString -> Int

O(1) Returns the number of Nibbles stored in the NibbleString.

The value returned will be double that stored in an identical ByteString.

pack :: [Nibble] -> NibbleString

O(n) Convert a [Nibble] into a NibbleString.

unpack :: NibbleString -> [Nibble]

O(n) Convert a NibbleString into a [Nibble].

byte2Nibbles :: Word8 -> [Nibble]

O(1) Convert one byte to a list of 2 Nibbles.

This can be useful in converting lists of bytes to a NibbleString.

nibbleString = pack $ byte2Nibbles =<< listOfBytes

isPrefixOf :: NibbleString -> NibbleString -> Bool

O(n) Returns True if the first NibbleString is a prefix of the second.

head :: NibbleString -> Nibble

O(1) Returns the first Nibble in a NibbleString.

tail :: NibbleString -> NibbleString

O(1) Returns the NibbleString remaining after removing the head Nibble.

cons :: Nibble -> NibbleString -> NibbleString

O(n) cons n s returns a new NibbleString by prepending n to the given NibbleString.

For $s$ of even length, the operation occurs in O(1), however for odd length, the underlying bytearray needs to be copied.

take :: Int -> NibbleString -> NibbleString

O(n) take n returns a new NibbleString by dropping the first n Nibbles from the given NibbleString.

Note- This works similarly to the ByteString version of take, although it runs at (worst case) in O(n). The reason for this, is, because if the even-odd nibbles are misaligned after the take, the whole array needs to be copied to shift things over correctly.

drop :: Int -> NibbleString -> NibbleString

O(1) drop n returns a new NibbleString by dropping the first n Nibbles from the given NibbleString.

append :: NibbleString -> NibbleString -> NibbleString

O(n) Creates a new NibbleString by appending one to another.