Data.ByteString.Unsafe

Copyright	(c) Don Stewart 2006-2008 (c) Duncan Coutts 2006-2011
License	BSD-style
Maintainer	dons00@gmail.com, duncan@community.haskell.org
Stability	provisional
Portability	non-portable
Safe Haskell	Unsafe
Language	Haskell98

Непроверенный доступ

unsafeHead :: ByteString -> Word8 Исходный код

Разнообразие head для непустых ByteStrings. unsafeHead опускает проверку на пустой случай, поэтому программист обязан предоставить доказательство, что ByteString не пустой.

unsafeTail :: ByteString -> ByteString Исходный код

Разнообразие tail для непустых ByteStrings. unsafeTail опускает проверку на пустой случай. Как и в случае с unsafeHead, программист должен предоставить отдельное доказательство, что ByteString не пустой.

unsafeInit :: ByteString -> ByteString Исходный код

Разнообразие init для непустых ByteStrings. unsafeInit опускает проверку на пустой случай. Как и в случае с unsafeHead, программист должен предоставить отдельное доказательство, что ByteString не пустой.

unsafeLast :: ByteString -> Word8 Исходный код

Разнообразие last для непустых ByteStrings. unsafeLast опускает проверку на пустой случай. Как и в случае с unsafeHead, программист должен предоставить отдельное доказательство, что ByteString не пустой.

unsafeIndex :: ByteString -> Int -> Word8 Исходный код

Небезопасный ByteString оператор индекса (подстроки), начиная с 0, возвращающий Word8. Это опускает проверку границ, что означает дополнительную обязанность программиста убедиться, что границы проверены каким-либо другим способом.

unsafeTake :: Int -> ByteString -> ByteString Исходный код

Разнообразие take , которое опускает проверки на n, поэтому программист обязан предоставить доказательство, что 0 <= n <= length xs.

unsafeDrop :: Int -> ByteString -> ByteString Исходный код

Разнообразие drop , которое опускает проверки на n, поэтому программист обязан предоставить доказательство, что 0 <= n <= length xs.

Взаимодействие низкого уровня с CStrings

Использование ByteStrings с функциями для CStrings

unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a Исходный код

O(1) построение Используйте ByteString с функцией, требующей CString.

Эта функция не выполняет копирование и просто разворачивает ByteString для отображения как CString. Она небезопасна по двум причинам:

• После вызова этой функции CString совместно использует буфер байтов с исходным ByteString. Таким образом, модификация CString, как в C, или с помощью poke, изменит содержимое ByteString, нарушая референциальную прозрачность. Другие ByteStrings , созданные посредством совместного использования (например, те, что получены с помощью take или drop ), также будут отражать эти изменения. Модификация CString нарушит референциальную прозрачность. Чтобы избежать этого, используйте useAsCString, которая создаёт копию исходного ByteString.
• CStrings часто передаются функциям, которые требуют, чтобы они имели нулевой терминатор. Если исходный ByteString не был нуль-терминирован, то и CString им не будет. Программист несет ответственность за обеспечение того, что ByteString действительно имеет нулевой терминатор. В случае сомнений, используйте useAsCString.

unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a Исходный код

O(1) построение Используйте ByteString с функцией, требующей CStringLen.

Эта функция не выполняет копирование и просто разворачивает ByteString для отображения как CStringLen. Она небезопасна:

• После вызова этой функции CStringLen совместно использует буфер байтов с исходным ByteString. Таким образом, модификация CStringLen, как в C, или с помощью poke, изменит содержимое ByteString, нарушая референциальную прозрачность. Другие ByteStrings , созданные посредством совместного использования (например, те, что получены с помощью take или drop ), также будут отражать эти изменения. Модификация CStringLen нарушит референциальную прозрачность. Чтобы избежать этого, используйте useAsCStringLen, которая создаёт копию исходного ByteString.

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

unsafePackCString :: CString -> IO ByteString Исходный код

O(n) Создаёт ByteString из CString. Эта величина не будет иметь финализатора, и не будет собираться сборщиком мусора Haskell. Длина ByteString вычисляется с помощью strlen(3), поэтому сложность — O(n).

Эта функция небезопасна. Если CString позже будет изменена, это изменение отразится в полученном ByteString, нарушая референциальную прозрачность.

unsafePackCStringLen :: CStringLen -> IO ByteString Исходный код

O(1) Создаёт ByteString из CStringLen. Эта величина не будет иметь финализатора, и не будет собираться сборщиком мусора Haskell. Эта операция имеет сложность O(1), так как мы уже знаем окончательный размер, поэтому strlen(3) не требуется.

Эта функция небезопасна. Если исходный CStringLen позже будет изменён, это изменение отразится в полученном ByteString, нарушая референциальную прозрачность.

unsafePackMallocCString :: CString -> IO ByteString Исходный код

O(n) Создаёт ByteString из выделенной в C CString. Эта величина будет иметь free(3) финализатор.

Эта функция небезопасна. Если исходный CString позже будет изменён, это изменение отразится в полученном ByteString, нарушая референциальную прозрачность.

Эта функция также небезопасна, если её финализатор вызывается дважды, что приведёт к ошибке double free, или если ей передаётся CString, не выделенный с помощью malloc.

unsafePackMallocCStringLen :: CStringLen -> IO ByteString Source

O(1) Построение ByteString из выделенного CStringLen. У этого значения будет связанный free(3) финализатор.

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

Эта функция также небезопасна, если вы вызовете её финализатор дважды, что приведёт к ошибке «double free», или если вы передадите ей CString, не выделенный с помощью malloc.

unsafePackAddress :: Addr# -> IO ByteString Source

O(n) Упаковка последовательности нуль-терминированных байтов, на которые указывает Addr# (произвольный машинный адрес, предположительно указывающий за пределами управляемой сборкой мусора кучи), в ByteString. Значительно более быстрый способ создания Addr# — это использование необработанной строковой литералы, чем упаковка упакованной строки. Необработанная строковая литерала компилируется GHC в статический char []. Определение длины строки требует вызова strlen(3), поэтому Addr# должен указывать на буфер с нуль-терминатором (как это происходит со строковыми литералами "string"# в GHC). Используйте unsafePackAddressLen, если длина строки известна статически.

Пример:

literalFS = unsafePackAddress "literal"#

Эта функция является небезопасной. Если вы измените буфер, на который указывает исходный Addr#, это изменение отразится в результирующем ByteString, нарушая референциальную прозрачность.

Обратите внимание, что это также не сработает, если ваш Addr# содержит в строке встроенные символы '\0', так как strlen вернёт слишком короткую длину.

unsafePackAddressLen :: Int -> Addr# -> IO ByteString Source

O(1) unsafePackAddressLen обеспечивает создание ByteString в постоянное время, что идеально подходит для строковых литералов. Она упаковывает последовательность байтов в ByteString, используя исходный Addr# на строку и длину строки.

Эта функция небезопасна по двум причинам:

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

Если есть сомнения, не используйте эту функцию.

unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString Source

O(1) Построение ByteString по заданному Ptr Word8 на буфер, длине и действию IO, представляющему финализатор. Эта функция недоступна в Hugs.

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

unsafeFinalize :: ByteString -> IO () Source

Явное выполнение финализатора, связанного со значением ByteString. Ссылки на это значение после финализации могут генерировать некорректные обращения к памяти.

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