Главная » Haskell » Модуль Base для работы с восьмибитовыми строками

0

Этот модуль является служебным и вряд ли должен использоваться программистом самостоятельно (хотя это возможно). В нём приводятся описания примитивов для работы с восьмибитовыми строками  (алгебраические типы данных и функции). Использование этого модуля выглядит так:

import Data.ByteString.Base

При этом надо учесть, что модуль ByteString сам по себе уже импортирует рассматриваемый модуль, реимпортируя часть его функций (которая может быть полезна стороннему разработчику программного обеспечения), поэтому если модуль ByteString уже использован, импортировать модуль Base не надо.

В этом модуле практически все программные сущности описаны в виде примитивов, поэтому в нижеследующем описании этот факт отмечаться не будет. Если для функции указана только сигнатура, то такая функция примитивна. Описание этого модуля в данном справочнике приводится для того, чтобы у читателя было понимание, какие  функции  используются для работы с восьмибитовыми строками. Кроме того, многие из функций, которые описаны ниже, используются в функциях модуля ByteString.

Однако в первую очередь в модуле описывается два алгебраических типа данных, которые позволяют работать с восьмибитовыми строками.

Тип: ByteString

Описание: эффективное представление восьмибитовых  строк, содержащих символы типа Word8.

Определение:

data  ByteString = PS  !(ForeignPtr Word8) !Int !Int

Для  данного типа определены  экземпляры следующих классов:  Data, Eq,

Monoid, Ord, Read, Show, Typeable.

Тип: LazyByteString

Описание: эффективное представление ленивых восьмибитовых строк, содержащих символы типа Word8.

Определение:

newtype LazyByteString = LPS  [ByteString]

Для данного типа определены экземпляры следующих классов:  Data, Read,

Show, Typeable.

Функция: unsafeHead

Описание: вариант функции head для непустых строк, который пропускает проверку на пустоту, поэтому обязанностью программиста  становится передача в эту функцию только непустых строк.

Определение:

unsafeHead :: ByteString ->  Word8 unsafeHead (PS x  s  l) =  assert (l > 0)  $

inlinePerformIO  $ withForeignPtr  x  $

\p ->  peekByteOff  p s

Функция: unsafeTail

Описание: вариант функции tail для непустых строк, который пропускает проверку на пустоту, поэтому обязанностью программиста  становится передача в эту функцию только непустых строк.

Определение:

unsafeTail :: ByteString  ->  ByteString

unsafeTail (PS ps s  l) = assert (l > 0)  $ PS  ps (s  +  1)  (l 1)

Функция: unsafeIndex

Описание: вариант функции index, который пропускает проверку вхождения заданного индекса в диапазон индексов строки (начиная с 0). Программист должен сам следить за тем, чтобы передаваемый индекс был в правильном диапазоне. Определение:

unsafeIndex   :: ByteString ->  Int ->  Word8

unsafeIndex   (PS x  s  l) i = assert (i >= 0  &&  i < l) $ inlinePerformIO  $ withForeignPtr  x  $

\p ->  peekByteOff  p (s + i)

Функция: unsafeTake

Описание: вариант функции take, который пропускает проверку вхождения заданного числа в диапазон индексов строки.  Программист должен сам следить за тем, чтобы передаваемое число символов, которое необходимо взять, лежало в интервале от 0 до длины строки.

Определение:

unsafeTake  :: Int ->  ByteString ->  ByteString

unsafeTake  n (PS x  s  l) = assert (0  <= n &&  n <= l) $  PS  x  s  n

Функция: unsafeDrop

Описание: вариант функции drop, который пропускает проверку вхождения заданного числа в диапазон индексов строки.  Программист  должен сам следить за тем, чтобы передаваемое число символов, которое необходимо взять, лежало в интервале от 0 до длины строки.

Определение:

unsafeDrop    :: Int ->  ByteString ->  ByteString

unsafeDrop  n (PS x  s  l) = assert (0  <= n &&  n <= l) $ PS  x  (s + n)  (l n)

Функция: empty

Описание: создаёт пустую восьмибитовую строку.

Определение:

empty ::  ByteString

Функция: create

Описание: создаёт восьмибитовую строку  заданного размера и  заполняет её при помощи заданной функции.

Определение:

create :: Int ->  (Ptr Word8 ->  IO ()) ->  IO  ByteString create l f = do fp < mallocByteString l

withForeignPtr fp $  \p  ->  f p return $!  PS  fp 0 l

Функция: createAndTrim

Описание: создаёт восьмибитовую строку размера, не более указанного, и заполняет её содержимым при помощи заданной функции. Функция  createAndTrim является основным эффективным механизмом создания  восьмибитовых строк в языке Haskell при работе со строками из языка C.

Определение:

createAndTrim  :: Int ->  (Ptr Word8 ->  IO Int) ->  IO  ByteString createAndTrim  l f = do fp < mallocByteString l

withForeignPtr  fp  $

\p ->  do l’ < f p

if assert (l’ <=  l) $ l’ >= l then return $!  PS  fp 0 l else  create l’ $

\p’ ->  memcpy  p’ p (fromIntegral  l’)

Функция: createAndTrim’

Описание: вариант функции createAndTrim, используемый в случаях, когда заданная функция для заполнения строки возвращает специальный результат. Определение:

createAndTrim’ :: Int ->  (Ptr Word8 ->  IO (Int, Int, a)) ->  IO  (ByteString, a) createAndTrim’ l f = do fp < mallocByteString l

withForeignPtr  fp  $

\p ->  do (off, l’, res) < f p

if assert (l’ <= l) $ l’ >= l

then  return $! (PS  fp 0 l, res) else  do  ps < create l’ $

\p’ ->  memcpy  p’  (p  ‘plusPtr‘  off) (fromIntegral  l’)

return $! (ps, res)

Функция: mallocByteString

Описание: обёртка над примитивной функцией для выделения памяти под восьмибитовую строку.

Определение:

mallocByteString :: Int ->  IO (ForeignPtr a)

Функция: unsafeCreate

Описание: создаёт восьмибитовую строку внутри монады IO.

Определение:

unsafeCreate  :: Int ->  (Ptr Word8 ->  IO ())  ->  ByteString unsafeCreate  l f =  unsafePerformIO   (create l f)

Функция:  unsafeUseAsCString

Описание: функция для использования восьмибитовой строки внутри функций, которые работают со строками в формате языка C. Возвращает результат работы такой функции в монаде IO.

Определение:

unsafeUseAsCString  :: ByteString ->  (CString ->  IO a)  ->  IO a unsafeUseAsCString  (PS ps s  _)  ac =  withForeignPtr ps $

\p ->  ac (castPtr p ‘plusPtr‘ s)

Функция: unsafeUseAsCStringLen

Описание: функция для использования восьмибитовой строки внутри функций, которые работают со строками в формате языка C (и принимают на вход данные типа CStringLen).  Возвращает результат работы такой функции в монаде IO. Определение:

unsafeUseAsCStringLen  :: ByteString ->  (CStringLen ->  IO a)  ->  IO a unsafeUseAsCStringLen  (PS ps s  l) f =  withForeignPtr  ps $

\p ->  f (castPtr p ‘plusPtr‘ s, l)

Функция: fromForeignPtr

Описание: конструирует восьмибитовую строку из указателя на внешнюю строку в формате языка C.

Определение:

fromForeignPtr :: ForeignPtr Word8 ->  Int ->  ByteString fromForeignPtr fp l = PS  fp 0 l

Функция: toForeignPtr

Описание: создаёт указатель на строку в формате языка C на основе заданной восьмибитовой строки.

Определение:

toForeignPtr :: ByteString ->  (ForeignPtr Word8,  Int, Int) toForeignPtr (PS ps s  l) = (ps, s, l)

Функция: packCStringFinalizer

Описание: создаёт строку при помощи заданных указателя на память в формате языка C, длины строки и действия в монаде IO, которое  произведёт финаль-

ную обработку созданной строки. Данная функция доступна только в поставке компилятора GHC.

Определение:

packCStringFinalizer :: Ptr   Word8 ->  Int ->  IO () ->  IO  ByteString

Функция: packAddress

Описание: упаковывает произвольную последовательность байт, оканчивающуюся нулевым символом, в восьмибитовую строку. Данная функция доступна только в поставке компилятора GHC.

Определение:

packAddress :: Addr#  ->  ByteString

Функция: unsafePackAddress

Описание: упаковывает заданное количество байт по требуемому адресу в восьмибитовую строку. Данная функция доступна только  в поставке  компилятора GHC.

Определение:

unsafePackAddress  :: Int ->  Addr#  ->  ByteString

Функция: unsafeFinalize

Описание: явно запускает функцию-финализатор, определённую для  заданной восьмибитовой строки. Вызвать эту функцию можно только один раз, поскольку  последующие вызовы могут вернуть  некорректный адрес. Данная функция доступна только в поставке компилятора GHC.

Определение:

unsafeFinalize ::  ByteString ->  IO ()

Функция: inlinePerformIO

Описание: инлайновое выполнение функции unsafePerformIO.

Определение:

inlinePerformIO :: IO  a ->  a inlinePerformIO  = unsafePerformIO

Функция: nullForeignPtr

Описание: возвращает пустой указатель на внешнюю память в формате языка C.

Определение:

nullForeignPtr :: ForeignPtr Word8

Функция: countOccurrences

Описание: подсчитывает количество проявлений определённого байта по заданному адресу.

Определение:

countOccurrences   :: (Storable a, Num  a)  => Ptr   a ->  Ptr   Word8 ->  Int  ->  IO () countOccurrences   :: (Storable a, Num  a)  => Ptr   a ->  Ptr  Word8 ->  Int ->  IO () countOccurrences   a b c  | a ‘seq‘ b ‘seq‘ c  ‘seq‘  False  = undefined countOccurrences   counts  str l = go 0

where

go a | a ‘seq‘ False  =  undefined go i | i == l        =  return ()

| otherwise = do k  < fromIntegral ‘fmap‘  peekElemOff str i x  < peekElemOff  counts  k

pokeElemOff counts  k  (x + 1) go (i + 1)

Функция: c-strlen

Описание: обёртка над функцией strlen из языка C.

Определение:

c_strlen :: CString ->  IO CSize

Функция: c-malloc

Описание: обёртка над функцией malloc  из языка C.

Определение:

c_malloc  :: CSize ->  IO (Ptr Word8)

Функция: c-free

Описание: обёртка над функцией free из языка C.

Определение:

c_free :: Ptr   Word8 ->  IO ()

Функция: c-free-finalizer

Описание: обёртка над функцией free_finalizer из языка C.

Определение:

c_free_finalizer :: FunPtr  (Ptr Word8 ->  IO ())

Функция: memchr

Описание: обёртка над функцией memchr из языка C.

Определение:

memchr  :: Ptr   Word8 ->  Word8 ->  CSize ->  IO (Ptr Word8)

Функция: memcmp

Описание: обёртка над функцией memcmp из языка C.

Определение:

memcmp  :: Ptr   Word8 ->  Ptr   Word8 ->  CSize ->  IO CInt

Функция: memcpy

Описание: обёртка над функцией memcpy из языка C.

Определение:

memcpy  :: Ptr   Word8 ->  Ptr   Word8 ->  CSize ->  IO ()

Функция: memmove

Описание: обёртка над функцией memmove из языка C.

Определение:

memmove  :: Ptr   Word8 ->  Ptr   Word8 ->  CSize ->  IO ()

Функция: memset

Описание: обёртка над функцией memset из языка C.

Определение:

memset  :: Ptr   Word8 ->  Word8 ->  CSize ->  IO (Ptr Word8)

Функция: c-reverse

Описание: обёртка над функцией reverse  из языка C.

Определение:

c_reverse :: Ptr   Word8 ->  Ptr   Word8 ->  CULong  ->  IO ()

Функция: c-intersperse

Описание: обёртка над функцией intersperse из языка C.

Определение:

c_intersperse :: Ptr   Word8 ->  Ptr   Word8 ->  CULong  ->  Word8  ->  IO ()

Функция: c-maximum

Описание: обёртка над функцией maximum из языка C.

Определение:

c_maximum  :: Ptr   Word8 ->  CULong  ->  IO Word8

Функция: c-minimum

Описание: обёртка над функцией minimum из языка C.

Определение:

c_minimum :: Ptr   Word8 ->  CULong  ->  IO Word8

Функция: c-count

Описание: обёртка над функцией count из языка C.

Определение:

c_count  :: Ptr   Word8 ->  CULong  ->  Word8 ->  IO  CULong

Функция: w2c

Описание: конвертирует  восьмибитовую строку,  содержащую  значения  типа

Word8, в строку, содержащую значения типа Char.

Определение:

w2c :: Word8  ->  Char

w2c = chr  .  fromIntegral

Функция: c2w

Описание: конвертирует  восьмибитовую строку,  содержащую  значения  типа Char, в строку, содержащую значения типа Word8.  Функция  небезопасна,  поскольку просто отсекает символы, до восьми битов. Является «квази»-обратной к функции w2c.

Определение:

c2w :: Char ->  Word8

c2w = fromIntegral . ord

Функция: isSpaceWord8

Описание: возвращает значение True, если заданный символ типа Word8 является

«пробельным».

Определение:

isSpaceWord8 ::  Word8 ->  Bool isSpaceWord8 w  =  case w  of

0x20  ->  True 0x0A  ->  True 0x09  ->  True 0x0C  ->  True 0x0D  ->  True 0x0B  ->  True 0xA0  ->  True

_        ->  False

Источник: Душкин Р. В., Справочник по языку Haskell. М.: ДМК Пресс, 2008. 544 с., ил.

По теме:

  • Комментарии