Data.ByteString.Char8

import qualified Data.ByteString.Char8 as C

Тип ByteString

data ByteString Источник

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

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

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

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

O(1) Пустая ByteString

singleton :: Символ -> ByteString Источник

O(1) Преобразование символа в ByteString

pack :: Строка -> ByteString Источник

O(n) Преобразование строки в ByteString

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

unpack :: ByteString -> [Символ] Источник

O(n) Преобразование ByteString в список символов.

Базовый интерфейс

cons :: Символ -> ByteString -> ByteString infixr 5 Источник

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

snoc :: ByteString -> Символ -> ByteString infixl 5 Источник

O(n) Добавление символа в конец ByteString. Подобно cons, эта функция выполняет memcpy.

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

init :: ByteString -> ByteString Source

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

null :: ByteString -> Bool Source

O(1) Проверка, является ли ByteString пустой.

length :: ByteString -> Int Source

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

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

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

O(n) map f xs — это ByteString, полученная путём применения f к каждому элементу xs.

reverse :: ByteString -> ByteString Source

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

intersperse :: Char -> ByteString -> ByteString Source

O(n) Функция intersperse принимает Char и ByteString и «вставляет» этот Char между элементами ByteString. Аналогична функции intersperse для списков.

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

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

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

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

Уменьшение ByteString (сводки)

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

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

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

'foldl\'' — это foldl, но строгий по отношению к аккумулятору.

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

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

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

Строгая версия foldl1

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

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

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

'foldr\'' — это строгая версия foldr.

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

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

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

Строгая версия foldr1

Специальные сводки

concat :: [ByteString] -> ByteString Source

O(n) Конкатенация списка ByteString.

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

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

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

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

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

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

maximum :: ByteString -> Char Source

maximum возвращает максимальное значение из ByteString.

minimum :: ByteString -> Char Source

minimum возвращает минимальное значение из ByteString

Создание ByteString

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

scanl :: (Char -> Char -> Char) -> Char -> 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 :: (Char -> Char -> Char) -> ByteString -> ByteString Source

scanl1 является вариантом scanl, не имеющим аргумента начального значения:

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

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

scanr — это дуальная функция scanl, работающая справа налево.

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

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

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

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

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

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

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

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

replicate :: Int -> Char -> 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 (Char, a)) -> a -> ByteString Source

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

Примеры:

unfoldr (\x -> if x <= '9' then Just (x, succ x) else Nothing) '0' == "0123456789"

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

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

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

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 :: (Char -> Bool) -> ByteString -> ByteString Source

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

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

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

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

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

spanEnd :: (Char -> 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 :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) Source

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

breakEnd :: (Char -> 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 :: (Char -> Char -> Bool) -> ByteString -> [ByteString] Source

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

inits :: ByteString -> [ByteString] Source

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

tails :: ByteString -> [ByteString] Source

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

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

split :: Char -> 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 :: (Char -> Bool) -> ByteString -> [ByteString] Source

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

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

Разбиение на строки и слова

lines :: ByteString -> [ByteString] Source

lines разбивает ByteString на список ByteString по символам новой строки. Результирующие строки не содержат символы новой строки.

words :: ByteString -> [ByteString] Source

words разбивает ByteString на список слов, ограниченные символами пробела.

unlines :: [ByteString] -> ByteString Source

unlines является обратной операцией к lines. Она объединяет строки, добавив завершающую новую строку к каждой.

unwords :: [ByteString] -> ByteString Source

Функция unwords аналогична функции unlines, но для слов.

Предикаты

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 Источник

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

Поиск в ByteString

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

elem :: Char -> ByteString -> Bool Источник

O(n) elem — это ByteString предикат членства. Эта реализация использует memchr(3).

notElem :: Char -> ByteString -> Bool Источник

O(n) notElem — это обратное elem

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

find :: (Char -> Bool) -> ByteString -> Maybe Char Источник

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

filter :: (Char -> Bool) -> ByteString -> ByteString Источник

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

Индексация ByteString

index :: ByteString -> Int -> Char Источник

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

elemIndex :: Char -> ByteString -> Maybe Int Источник

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

elemIndices :: Char -> ByteString -> [Int] Источник

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

elemIndexEnd :: Char -> ByteString -> Maybe Int Источник

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

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

findIndex :: (Char -> Bool) -> ByteString -> Maybe Int Источник

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

findIndices :: (Char -> Bool) -> ByteString -> [Int] Источник

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

count :: Char -> ByteString -> Int Источник

count возвращает количество раз, когда ее аргумент встречается в ByteString

count = length . elemIndices

Также

count '\n' == length . lines

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

Сцепление и расцепление ByteString

zip :: ByteString -> ByteString -> [(Char, Char)] Источник

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

zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a] Источник

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

unzip :: [(Char, Char)] -> (ByteString, ByteString) Источник

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

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

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

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

Чтение из ByteString

readInt :: ByteString -> Maybe (Int, ByteString) Source

readInt считывает целое число Int из начала ByteString. Если в начале строки нет целого числа, возвращает Nothing, иначе возвращает прочитанное целое число и остаток строки.

readInteger :: ByteString -> Maybe (Integer, ByteString) Source

readInteger считывает целое число Integer из начала ByteString. Если в начале строки нет целого числа, возвращает Nothing, иначе возвращает прочитанное целое число и остаток строки.

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

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

copy :: ByteString -> ByteString Source

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

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

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 в качестве CStrings

useAsCString :: ByteString -> (CString -> IO a) -> IO a Source

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

useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a Source

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

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

Ввод-вывод ByteString использует двоичный режим без декодирования символов или преобразования символов перевода строки. То, что он не учитывает режим перевода строки в файле, считается недостатком и может быть изменено в будущей версии.

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

getLine :: IO ByteString Source

Считывает строку из стандартного ввода.

getContents :: IO ByteString Source

getContents. Чёткое считывание стандартного ввода. Эквивалентно hGetContents stdin. Файл Handle закрывается после чтения содержимого.

putStr :: ByteString -> IO () Source

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

putStrLn :: ByteString -> IO () Source

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

interact :: (ByteString -> ByteString) -> IO () Source

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

Файлы

readFile :: FilePath -> IO ByteString Source

Чётко считывает весь файл в ByteString. Это гораздо эффективнее, чем считывание символов в String и последующее использование pack. Также может быть более эффективным, чем открытие файла и чтение с помощью hGet.

writeFile :: FilePath -> ByteString -> IO () Source

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

appendFile :: FilePath -> ByteString -> IO () Source

Добавляет ByteString в файл.

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

hGetLine :: Handle -> IO ByteString Source

Считывает строку из дескриптора.

hGetContents :: Handle -> IO ByteString Source

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

hGet :: Handle -> Int -> IO ByteString Source

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

hGet реализована через hGetBuf.

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

hGetSome :: Handle -> Int -> IO ByteString Source

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

hGetNonBlocking :: Handle -> Int -> IO ByteString Source

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

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

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

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

hPutNonBlocking :: Handle -> ByteString -> IO ByteString Source

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

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

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

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

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

Запись ByteString в дескриптор файла, добавляя байт новой строки