Главная » Haskell » Модуль String

0

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

import  Foreign.C.String

Процесс маршалинга (маршализация) преобразует каждый символ в формате языка Haskell (представление символа формата Unicode) в один или несколько байт, как это определено текущими установками системы локализации. Как следствие, нет никаких гарантий того, что получающаяся строка в формате языка C будет соответствовать по длине строке в формате языка Haskell. Преобразование между  представлением строки в формате языка Haskell и текущим форматом системы локализации может быть теряющим информацию.

Для представления обычных строк в формате языка C используются следующие типы данных.

Тип: CString

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

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

type  CString =  Ptr   CChar

Тип: CStringLen

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

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

type  CStringLen  = (Ptr  CChar, Int)

Функция: peekCString

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

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

peekCString  :: CString  -> IO String peekCString  = peekCAString

Функция: peekCStringLen

Описание: маршализует строку с явно заданной длиной в строку в формате языка Haskell.

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

peekCStringLen  :: CStringLen  -> IO String peekCStringLen  =  peekCAStringLen

Функция: newCString

Описание: маршализует строку в формате языка Haskell в строку в формате языка C, при этом исходная строка не должна содержать символов с нулевым кодом. Новая строка в формате языка C после использования должна быть явно удалена при помощи функций free (см. стр. 447) или finalizerFree (см. стр. 447). Определение:

newCString  :: String  ->  IO CString newCString =  newCAString

Функция: newCStringLen

Описание: маршализует строку в формате языка Haskell в строку в формате языка C. Новая строка в формате языка C с явно заданной длиной после использования должна быть явно удалена при помощи функций free (см. стр. 447) или finalizerFree (см. стр. 447).

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

newCStringLen :: String ->  IO  CStringLen newCStringLen =  newCAStringLen

Функция: withCString

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

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

withCString :: String ->  (CString ->  IO a)  ->  IO a withCString = withCAString

Функция: withCStringLen

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

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

withCStringLen :: String ->  (CStringLen ->  IO a)  ->  IO a withCStringLen = withCAStringLen

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

Функция: charIsRepresentable

Описание: возвращает значение True, если заданный символ может быть безопасно представлен в формате строк языка C. Все те символы, для которых этот предикат возвращает значение False, при преобразовании становятся символом (?). На текущий момент представимыми являются только символы таблицы Latin-1 из кодировки Unicode.

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

charIsRepresentable :: Char ->  IO  Bool charIsRepresentable c  =  return (ord c  < 256)

Функция: castCharToCChar

Описание: преобразует символ в формате языка Haskell в формат языка C. Эта функция безопасна только для символов с кодами, меньшими 256. Для символов с большими кодами происходит потеря информации.

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

castCharToCChar :: Char ->  CChar castCharToCChar ch =  fromIntegral (ord ch)

Функция: castCCharToChar

Описание: функция, обратная по действию функции castCharToCChar, поскольку  преобразует  символ таблицы Latin-1  в  формате языка C в формат языка Haskell.

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

castCCharToChar ::  CChar ->  Char

castCCharToChar ch = chr  (fromIntegral (fromIntegral  ch  :: Word8))

Функция: peekCAString

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

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

peekCAString  :: CString ->  IO  String peekCAString  cp = do cs  < peekArray0  nUL cp

return  (cCharsToChars  cs)

Функция: peekCAStringLen

Описание: маршализует строку с явно заданной длиной в строку в формате языка Haskell.

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

peekCAStringLen  :: CStringLen  ->  IO  String peekCAStringLen  (cp, len) = do cs  < peekArray  len  cp

return  (cCharsToChars  cs)

Функция: newCAString

Описание: маршализует строку в формате языка Haskell в строку в формате языка C, при этом исходная строка не должна содержать символов с нулевым кодом. Новая строка в формате языка C после использования должна быть явно удалена при помощи функций free (см. стр. 447) или finalizerFree (см. стр. 447). Определение:

newCAString :: String ->  IO CString newCAString = newArray0 nUL .  charsToCChars

Функция: newCAStringLen

Описание: маршализует строку в формате языка Haskell в строку в формате языка C. Новая строка в формате языка C с явно заданной длиной после использования должна быть явно удалена при помощи функций free (см. стр. 447) или finalizerFree (см. стр. 447).

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

newCAStringLen :: String ->  IO  CStringLen

newCAStringLen str = do a < newArray  (charsToCChars  str) return  (pairLength str  a)

Функция: withCAString

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

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

withCAString :: String ->  (CString ->  IO a)  ->  IO a withCAString = withArray0 nUL .  charsToCChars

Функция: withCAStringLen

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

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

withCAStringLen :: String ->  (CStringLen ->  IO  a)  ->  IO a

withCAStringLen str act  = withArray (charsToCChars  str) $ act  .  pairLength str

Также в этом модуле описаны функции для маршалинга «широких» строк, использующихся в языке  C для представления  символов в кодировке  Unicode (UTF-32 или UTF-16). Для представления таких строк в формате языка C используются следующие типы данных.

Тип: CWString

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

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

type  CWString  =  Ptr   CWchar

Тип: CWStringLen

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

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

type  CWStringLen = (Ptr  CWchar, Int)

Функция: peekCWString

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

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

peekCWString :: CWString ->  IO  String peekCWString cp = do cs  < peekArray0  wNUL  cp

return (cWcharsToChars cs)

Функция: peekCWStringLen

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

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

peekCWStringLen :: CWStringLen ->  IO String peekCWStringLen (cp, len) = do cs  < peekArray  len  cp

return  (cWcharsToChars  cs)

Функция: newCWString

Описание: маршализует строку  в формате языка  Haskell в широкую  строку в формате языка C, при этом исходная строка не должна содержать символов с нулевым кодом. Новая строка в формате языка C после использования должна быть явно удалена при помощи функций free (см. стр. 447) или finalizerFree (см. стр. 447).

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

newCWString :: String ->  IO CWString newCWString = newArray0 wNUL  .  charsToCWchars

Функция: newCWStringLen

Описание: маршализует строку  в формате языка  Haskell в широкую  строку в формате языка C. Новая строка в формате языка C с явно  заданной длиной после использования  должна быть явно удалена при помощи функций free (см. стр. 447) или finalizerFree (см. стр. 447).

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

newCWStringLen  :: String ->  IO  CWStringLen

newCWStringLen  str = do a < newArray  (charsToCWchars str) return  (pairLength str  a)

Функция: withCWString

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

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

withCWString  :: String ->  (CWString  ->  IO a)  ->  IO a withCWString  = withArray0 wNUL  .  charsToCWchars

Функция: withCWStringLen

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

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

withCWStringLen  :: String ->  (CWStringLen  ->  IO  a)  ->  IO a

withCWStringLen  str act  = withArray (charsToCWchars str) $ act  .  pairLength str

Также  в  этом  модуле определены дополнительные служебные  функции для преобразования, а также  константные  функции,  используемые в процессе преобразования. Узнать их состав и понять суть их работы можно, обратившись к исходному коду модуля.

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

По теме:

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