Data.ByteString

import qualified Data.ByteString as B

Тип ByteString

data ByteString Источник

Эффективная в отношении памяти структура данных для вектора Word8, поддерживающая множество эффективных операций.

ByteString содержит 8-битные байты, или, используя операции из Data.ByteString.Char8, может интерпретироваться как содержащий 8-битные символы.

Введение и удаление ByteString

empty :: ByteString Источник

O(1) Пустой ByteString

singleton :: Word8 -> ByteString Источник

O(1) Преобразование Word8 в ByteString

pack :: [Word8] -> ByteString Источник

O(n) Преобразование '[Word8]' в ByteString.

Для приложений с большим количеством строковых литералов pack может быть узким местом. В таких случаях рассмотрите использование packAddress (только GHC).

unpack :: ByteString -> [Word8] Источник

O(n) Преобразование ByteString в '[Word8]'.

Основной интерфейс

cons :: Word8 -> ByteString -> ByteString infixr 5 Источник

O(n) cons аналогично (:) для списков, но с другой сложностью, так как требует создания копии.

snoc :: ByteString -> Word8 -> ByteString infixl 5 Источник

O(n) Добавление байта в конец ByteString

append :: ByteString -> ByteString -> ByteString Источник

O(n) Присоединение двух ByteStrings

init :: ByteString -> ByteString Source

O(1) Возвращает все элементы ByteString, кроме последнего. В случае пустого ByteString будет выброшено исключение.

null :: ByteString -> Bool Source

O(1) Проверяет, является ли ByteString пустым.

length :: ByteString -> Int Source

O(1) length возвращает длину ByteString как Int.

Преобразование ByteStrings

map :: (Word8 -> Word8) -> ByteString -> ByteString Source

O(n) map f xs представляет собой ByteString, полученный путем применения f к каждому элементу xs.

reverse :: ByteString -> ByteString Source

O(n) reverse xs эффективно возвращает элементы xs в обратном порядке.

intersperse :: Word8 -> ByteString -> ByteString Source

O(n) Функция intersperse принимает Word8 и ByteString и "вставляет" этот байт между элементами ByteString. Она аналогична функции intersperse для списков.

intercalate :: ByteString -> [ByteString] -> ByteString Source

O(n) Функция intercalate принимает ByteString и список ByteString и конкатенирует список после вставки первого аргумента между каждым элементом списка.

transpose :: [ByteString] -> [ByteString] Source

Функция transpose транспонирует строки и столбцы своего аргумента ByteString.

Сворачивание ByteStrings (folds)

foldl :: (a -> Word8 -> a) -> a -> ByteString -> a Source

foldl, применённая к бинарному оператору, начальному значению (обычно левому нейтральному элементу оператора) и ByteString, сворачивает ByteString, используя бинарный оператор, слева направо.

foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a Source

foldl' похожа на foldl, но строгая в отношении накопителя.

foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 Source

foldl1 является вариантом foldl, который не имеет аргумента начального значения, и поэтому должен применяться к непустым ByteStrings. В случае пустого ByteString будет выброшено исключение.

foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 Source

'foldl1\'' похожа на foldl1, но строгая в отношении накопителя. В случае пустого ByteString будет выброшено исключение.

foldr :: (Word8 -> a -> a) -> a -> ByteString -> a Source

foldr, применённая к бинарному оператору, начальному значению (обычно правому нейтральному элементу оператора) и ByteString, сворачивает ByteString, используя бинарный оператор, справа налево.

foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a Source

foldr' похожа на foldr, но строгая в отношении накопителя.

foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 Source

foldr1 является вариантом foldr, который не имеет аргумента начального значения, и поэтому должен применяться к непустым ByteString. В случае пустого ByteString будет выброшено исключение.

foldr1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 Source

'foldr1\'' является вариантом foldr1, но строгая в отношении накопителя.

Специальные сворачивания

concat :: [ByteString] -> ByteString Source

O(n) Конкатенирует список ByteStrings.

concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString Source

Применяет функцию к ByteString и конкатенирует результаты.

any :: (Word8 -> Bool) -> ByteString -> Bool Source

O(n) Применённая к предикату и ByteString, any определяет, удовлетворяет ли какой-либо элемент ByteString предикату.

all :: (Word8 -> Bool) -> ByteString -> Bool Source

O(n) Применённая к предикату и ByteString, all определяет, удовлетворяют ли все элементы ByteString предикату.

maximum :: ByteString -> Word8 Source

O(n) maximum возвращает максимальное значение из ByteString. Эта функция будет слияна. В случае пустого ByteString будет выброшено исключение.

minimum :: ByteString -> Word8 Source

O(n) minimum возвращает минимальное значение из ByteString. Эта функция будет слияна. В случае пустого ByteString будет выброшено исключение.

Создание ByteString

Сканирование

scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString Source

scanl аналогично foldl, но возвращает список последовательных уменьшенных значений слева. Эта функция будет слияна.

scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]

Обратите внимание, что

last (scanl f z xs) == foldl f z xs.

scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString Source

scanl1 является вариантом scanl, который не имеет аргумента начального значения. Эта функция будет слияна.

scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]

scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString Source

scanr — это правая двойственная операция scanl.

scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString Source

scanr1 является вариантом scanr, который не имеет аргумента начального значения.

scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]

Накопление отображений

mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) Source

Функция mapAccumL ведет себя как сочетание map и foldl; она применяет функцию к каждому элементу ByteString, передавая параметр накопления слева направо и возвращая конечное значение этого параметра вместе с новым списком.

mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) Source

Функция mapAccumR ведет себя как сочетание map и foldr; она применяет функцию к каждому элементу ByteString, передавая параметр накопления справа налево и возвращая конечное значение этого параметра вместе с новым ByteString.

Генерация и развертывание ByteString

replicate :: Int -> Word8 -> ByteString Source

O(n) replicate n x — это ByteString длины n со значением x каждого элемента. Выполняется следующее:

replicate w c = unfoldr w (\u -> Just (u,u)) c

Эта реализация использует memset(3)

unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString Source

O(n), где n — длина результата. Функция unfoldr аналогична List 'unfoldr'. unfoldr строит ByteString из начального значения. Функция принимает элемент и возвращает Nothing, если завершила создание ByteString, или возвращает Just (a,b), в этом случае a — следующий байт в строке, а b — начальное значение для дальнейшего создания.

Примеры:

   unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
== pack [0, 1, 2, 3, 4, 5]

unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a) Source

O(n) Как и unfoldr, unfoldrN строит ByteString из начального значения. Однако длина результата ограничена первым аргументом unfoldrN. Эта функция более эффективна, чем unfoldr, когда максимальная длина результата известна.

Следующее уравнение связывает unfoldrN и unfoldr:

fst (unfoldrN n f s) == take n (unfoldr f s)

Подстроки

Разбитие строк

take :: Int -> ByteString -> ByteString Source

O(1) take n, применённая к ByteString xs, возвращает префикс xs длиной n, или xs само, если n > length xs.

drop :: Int -> ByteString -> ByteString Source

O(1) drop n xs возвращает суффикс xs после первых n элементов, или [] если n > length xs.

splitAt :: Int -> ByteString -> (ByteString, ByteString) Source

O(1) splitAt n xs эквивалентно (take n xs, drop n xs).

takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString Source

takeWhile, применённая к предикату p и ByteString xs, возвращает самый длинный префикс (возможно, пустой) xs элементов, удовлетворяющих p.

dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString Source

dropWhile p xs возвращает суффикс, оставшийся после takeWhile p xs.

span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) Source

span p xs разбивает ByteString на два сегмента. Она эквивалентна (takeWhile p xs, dropWhile p xs)

spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) Source

spanEnd ведет себя как span, но с конца ByteString. У нас есть

spanEnd (not.isSpace) "x y z" == ("x y ","z")

и

spanEnd (not . isSpace) ps
   == 
let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x) 

break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) Source

break p эквивалентно span (not . p).

Под GHC правило переписывания преобразует break (==) в вызов специализированной функции breakByte:

break ((==) x) = breakByte x
break (==x) = breakByte x

breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) Source

breakEnd ведет себя как break но с конца ByteString

breakEnd p == spanEnd (not.p)

group :: ByteString -> [ByteString] Source

Функция group принимает ByteString и возвращает список ByteString, такое, что конкатенация результата равна аргументу. Более того, каждый подсписок в результате содержит только равные элементы. Например,

group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]

Это частный случай groupBy, который позволяет программисту указать собственное условие равенства. Он примерно на 40% быстрее, чем groupBy (==)

groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString] Source

Функция groupBy — это неперегруженная версия group.

inits :: ByteString -> [ByteString] Source

O(n) Возвращает все начальные сегменты заданного ByteString, самые короткие в первую очередь.

tails :: ByteString -> [ByteString] Source

O(n) Возвращает все конечные сегменты заданного ByteString, самые длинные в первую очередь.

Разбиение на подстроки

split :: Word8 -> ByteString -> [ByteString] Source

O(n) Разбивает ByteString на части, разделенные байтом-аргументом, потребляя разделитель. То есть

split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
split 'a'  "aXaXaXa"    == ["","X","X","X",""]
split 'x'  "x"          == ["",""]

и

intercalate [c] . split c == id
split == splitWith . (==)

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

splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString] Source

O(n) Разделяет ByteString на компоненты, ограниченные разделителями, где предикат возвращает True для разделительного элемента. Результирующие компоненты не содержат разделители. Два смежных разделителя приводят к пустому компоненту в выводе. Например:

splitWith (=='a') "aabbaca" == ["","","bb","c",""]
splitWith (=='a') []        == []

Предикаты

isPrefixOf :: ByteString -> ByteString -> Bool Source

O(n) Функция isPrefixOf принимает две ByteString и возвращает True тогда и только тогда, когда первая является префиксом второй.

isSuffixOf :: ByteString -> ByteString -> Bool Source

O(n) Функция isSuffixOf принимает две ByteString и возвращает True тогда и только тогда, когда первая является суффиксом второй.

Следующее выполняется:

isSuffixOf x y == reverse x `isPrefixOf` reverse y

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

isInfixOf :: ByteString -> ByteString -> Bool Source

Проверяет, является ли одна строка подстрокой другой. isInfixOf p s эквивалентно not (null (findSubstrings p s)).

Поиск произвольных подстрок

breakSubstring Source

Разбивает строку по подстроке, возвращая пару: часть строки до совпадения и остаток строки.

Следующие соотношения выполняются:

break (== c) l == breakSubstring (singleton c) l

и:

findSubstring s l ==
   if null s then Just 0
             else case breakSubstring s l of
                      (x,y) | null y    -> Nothing
                            | otherwise -> Just (length x)

Например, для токенизации строки, опуская разделители:

tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
    where (h,t) = breakSubstring x y

Для перехода к первой вхождения строки:

snd (breakSubstring x y) 

Для взятия частей строки перед разделителем:

fst (breakSubstring x y) 

findSubstring Source

Получить первый индекс подстроки в другой строке или Nothing, если строка не найдена. findSubstring p s эквивалентно listToMaybe (findSubstrings p s).

findSubstrings Source

Найти индексы всех (возможно перекрывающихся) вхождений подстроки в строке.

Поиск в ByteString

Поиск по равенству

elem :: Word8 -> ByteString -> Bool Source

O(n) elem — это предикат принадлежности ByteString.

notElem :: Word8 -> ByteString -> Bool Source

O(n) notElem является обратной операцией к elem

Поиск с помощью предиката

find :: (Word8 -> Bool) -> ByteString -> Maybe Word8 Source

O(n) Функция find принимает предикат и ByteString, и возвращает первый элемент, удовлетворяющий предикату, или Nothing, если такого элемента нет.

find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing

filter :: (Word8 -> Bool) -> ByteString -> ByteString Source

O(n) Применённая к предикату и ByteString, функция возвращает ByteString, содержащую те символы, которые удовлетворяют предикату.

partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) Source

O(n) Функция partition принимает предикат и ByteString, и возвращает пару ByteString'ов, содержащую элементы, удовлетворяющие и не удовлетворяющие предикату соответственно; т.е.,

partition p bs == (filter p xs, filter (not . p) xs)

Индексирование ByteString

index :: ByteString -> Int -> Word8 Source

O(1) Оператор индекса (индексации), начиная с 0.

elemIndex :: Word8 -> ByteString -> Maybe Int Source

O(n) Функция elemIndex возвращает индекс первого элемента в заданном ByteString, который равен запрошенному элементу, или Nothing, если такого элемента нет. В данной реализации используется memchr(3).

elemIndices :: Word8 -> ByteString -> [Int] Source

O(n) Функция elemIndices расширяет функциональность elemIndex, возвращая индексы всех элементов, равных запрошенному элементу, в порядке возрастания. В данной реализации используется memchr(3).

elemIndexEnd :: Word8 -> ByteString -> Maybe Int Source

O(n) Функция elemIndexEnd возвращает последний индекс элемента в заданном ByteString, равного запрошенному элементу, или Nothing, если такого элемента нет. Следующее выполняется:

elemIndexEnd c xs == 
(-) (length xs - 1) `fmap` elemIndex c (reverse xs)

findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int Source

Функция findIndex принимает предикат и ByteString и возвращает индекс первого элемента в ByteString, удовлетворяющего предикату.

findIndices :: (Word8 -> Bool) -> ByteString -> [Int] Source

Функция findIndices расширяет findIndex, возвращая индексы всех элементов, удовлетворяющих предикату, в порядке возрастания.

count :: Word8 -> ByteString -> Int Source

Функция count возвращает количество вхождений своего аргумента в ByteString

count = length . elemIndices

Но более эффективно, чем использование length на промежуточном списке.

Сборка и разборка ByteString

zip :: ByteString -> ByteString -> [(Word8, Word8)] Source

O(n) zip принимает две ByteString и возвращает список соответствующих пар байтов. Если одна из входных ByteString короче, лишние элементы более длинной ByteString отбрасываются. Эквивалентно паре операций unpack

zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a] Source

zipWith обобщает zip путём сборки с использованием функции, переданной в качестве первого аргумента, вместо функции формирования кортежей. Например, zipWith (+) применяется к двум ByteString для получения списка соответствующих сумм.

unzip :: [(Word8, Word8)] -> (ByteString, ByteString) Source

O(n) unzip преобразует список пар байтов в пару ByteString. Обратите внимание, что это выполняет две операции pack

Отсортированные ByteString

sort :: ByteString -> ByteString Source

O(n) Эффективно сортирует ByteString, используя сортировку подсчётом.

Преобразования низкого уровня

Копирование ByteString

copy :: ByteString -> ByteString Source

O(n) Создаёт копию ByteString со своим хранилищем. Это преимущественно полезно, чтобы позволить остальной части данных, на которые указывает ByteString, быть удалённой сборщиком мусора, например, если большая строка была прочитана, и только небольшая часть её нужна в остальной части программы.

Упаковка CString и указателей

packCString :: CString -> IO ByteString Source

O(n). Создаёт новую ByteString из CString. Полученная ByteString является неизменяемой копией исходной CString, и управляется на стеке Haskell. Исходная CString должна быть завершена нулём.

packCStringLen :: CStringLen -> IO ByteString Source

O(n). Создать новый ByteString из CStringLen. Результирующий ByteString — это неизменяемая копия исходного CStringLen. ByteString — это обычное значение Haskell и будет управляться на куче Haskell.

Использование ByteStrings в качестве CString

useAsCString :: ByteString -> (CString -> IO a) -> IO a Источник

O(n) построение Используйте ByteString с функцией, требующей нуль-терминированного CString. CString — это копия и будет освобождена автоматически.

useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a Источник

O(n) построение Используйте ByteString с функцией, требующей CStringLen. Как и useAsCString, эта функция создаёт копию исходного ByteString.

Ввод-вывод с ByteString

Стандартный ввод и вывод

getLine :: IO ByteString Источник

Прочитать строку из стандартного ввода.

getContents :: IO ByteString Источник

getContents. Читать stdin строго. Эквивалентно hGetContents stdin. Handle закрывается после того, как содержимое будет считано.

putStr :: ByteString -> IO () Источник

Записать ByteString в стандартный вывод.

putStrLn :: ByteString -> IO () Источник

Записать ByteString в стандартный вывод, добавив байт новой строки.

interact :: (ByteString -> ByteString) -> IO () Источник

Функция interact принимает функцию типа ByteString -> ByteString в качестве аргумента. Всё входное содержимое со стандартного устройства ввода передаётся в эту функцию в качестве аргумента, а полученная строка выводится на стандартное устройство вывода.

Файлы

readFile :: FilePath -> IO ByteString Источник

Прочитать весь файл строго в ByteString.

writeFile :: FilePath -> ByteString -> IO () Источник

Записать ByteString в файл.

appendFile :: FilePath -> ByteString -> IO () Источник

Добавить ByteString в файл.

Ввод-вывод с дескрипторами

hGetLine :: Handle -> IO ByteString Источник

Прочитать строку из дескриптора.

hGetContents :: Handle -> IO ByteString Источник

Прочитать всё содержимое дескриптора строго в ByteString.

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

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

hGet :: Handle -> Int -> IO ByteString Источник

Прочитать ByteString напрямую из указанного Handle. Это намного эффективнее, чем чтение символов в String и затем использование pack. Первый аргумент — дескриптор для чтения, а второй — количество байтов для чтения. Возвращает прочитанные байты, до n, или empty, если достигнут конец файла.

hGet реализовано в терминах hGetBuf.

Если дескриптор является конвейером или сокетом, а записывающий конец закрыт, hGet будет вести себя так, как будто достигнут конец файла.

hGetSome :: Handle -> Int -> IO ByteString Источник

Подобно hGet, за исключением того, что может быть возвращён более короткий ByteString если доступно недостаточно байтов для удовлетворения всего запроса. hGetSome блокируется только если нет данных, и конец файла ещё не достигнут.

hGetNonBlocking :: Handle -> Int -> IO ByteString Источник

hGetNonBlocking аналогично hGet, за исключением того, что он никогда не будет блокироваться, ожидая появления данных, вместо этого возвращая только доступные данные. Если данных для чтения нет, hGetNonBlocking возвращает empty.

Примечание: в Windows и с реализацией Haskell, отличной от GHC, эта функция не работает правильно; она ведет себя идентично hGet.

hPut :: Handle -> ByteString -> IO () Источник

Выводит ByteString в указанный Handle.

hPutNonBlocking :: Handle -> ByteString -> IO ByteString Источник

Аналогично hPut, за исключением того, что никогда не будет блокироваться. Вместо этого возвращает любой хвост, который не был записан. Этот хвост может быть empty в случае, если вся строка была записана, или вся исходная строка, если ничего не было записано. Также возможны частичные записи.

Примечание: в Windows и с реализацией Haskell, отличной от GHC, эта функция не работает правильно; она ведет себя идентично hPut.

hPutStr :: Handle -> ByteString -> IO () Источник

Синоним для hPut, для совместимости

hPutStrLn :: Handle -> ByteString -> IO () Source

Записывает ByteString в обработчик, добавляя байт новой строки в конец.

breakByte :: Word8 -> ByteString -> (ByteString, ByteString) Source

breakByte разбивает свой аргумент ByteString на первой встрече указанного байта. Она более эффективна, чем break, так как она реализована с помощью memchr(3). То есть:

break (=='c') "abcd" == breakByte 'c' "abcd"