Safe Haskell | None |
---|---|
Language | Haskell2010 |
System.OsString.Internal
Synopsis
- encodeUtf :: MonadThrow m => String -> m OsString
- unsafeEncodeUtf :: HasCallStack => String -> OsString
- encodeWith :: TextEncoding -> TextEncoding -> String -> Either EncodingException OsString
- encodeFS :: String -> IO OsString
- decodeUtf :: MonadThrow m => OsString -> m String
- decodeWith :: TextEncoding -> TextEncoding -> OsString -> Either EncodingException String
- decodeFS :: OsString -> IO String
- fromBytes :: MonadThrow m => ByteString -> m OsString
- osstr :: QuasiQuoter
- unpack :: OsString -> [OsChar]
- pack :: [OsChar] -> OsString
- empty :: OsString
- singleton :: OsChar -> OsString
- unsafeFromChar :: Char -> OsChar
- toChar :: OsChar -> Char
- snoc :: OsString -> OsChar -> OsString
- cons :: OsChar -> OsString -> OsString
- last :: HasCallStack => OsString -> OsChar
- tail :: HasCallStack => OsString -> OsString
- uncons :: OsString -> Maybe (OsChar, OsString)
- head :: HasCallStack => OsString -> OsChar
- init :: HasCallStack => OsString -> OsString
- unsnoc :: OsString -> Maybe (OsString, OsChar)
- null :: OsString -> Bool
- length :: OsString -> Int
- map :: (OsChar -> OsChar) -> OsString -> OsString
- reverse :: OsString -> OsString
- intercalate :: OsString -> [OsString] -> OsString
- foldl :: (a -> OsChar -> a) -> a -> OsString -> a
- foldl' :: (a -> OsChar -> a) -> a -> OsString -> a
- foldl1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
- foldl1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
- foldr :: (OsChar -> a -> a) -> a -> OsString -> a
- foldr' :: (OsChar -> a -> a) -> a -> OsString -> a
- foldr1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
- foldr1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
- all :: (OsChar -> Bool) -> OsString -> Bool
- any :: (OsChar -> Bool) -> OsString -> Bool
- concat :: [OsString] -> OsString
- replicate :: Int -> OsChar -> OsString
- unfoldr :: (a -> Maybe (OsChar, a)) -> a -> OsString
- unfoldrN :: Int -> (a -> Maybe (OsChar, a)) -> a -> (OsString, Maybe a)
- take :: Int -> OsString -> OsString
- takeEnd :: Int -> OsString -> OsString
- takeWhileEnd :: (OsChar -> Bool) -> OsString -> OsString
- takeWhile :: (OsChar -> Bool) -> OsString -> OsString
- drop :: Int -> OsString -> OsString
- dropEnd :: Int -> OsString -> OsString
- dropWhile :: (OsChar -> Bool) -> OsString -> OsString
- dropWhileEnd :: (OsChar -> Bool) -> OsString -> OsString
- breakEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
- break :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
- span :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
- spanEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
- splitAt :: Int -> OsString -> (OsString, OsString)
- split :: OsChar -> OsString -> [OsString]
- splitWith :: (OsChar -> Bool) -> OsString -> [OsString]
- stripSuffix :: OsString -> OsString -> Maybe OsString
- stripPrefix :: OsString -> OsString -> Maybe OsString
- isInfixOf :: OsString -> OsString -> Bool
- isPrefixOf :: OsString -> OsString -> Bool
- isSuffixOf :: OsString -> OsString -> Bool
- breakSubstring :: OsString -> OsString -> (OsString, OsString)
- elem :: OsChar -> OsString -> Bool
- find :: (OsChar -> Bool) -> OsString -> Maybe OsChar
- filter :: (OsChar -> Bool) -> OsString -> OsString
- partition :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
- index :: HasCallStack => OsString -> Int -> OsChar
- indexMaybe :: OsString -> Int -> Maybe OsChar
- (!?) :: OsString -> Int -> Maybe OsChar
- elemIndex :: OsChar -> OsString -> Maybe Int
- elemIndices :: OsChar -> OsString -> [Int]
- count :: OsChar -> OsString -> Int
- findIndex :: (OsChar -> Bool) -> OsString -> Maybe Int
- findIndices :: (OsChar -> Bool) -> OsString -> [Int]
Documentation
encodeUtf :: MonadThrow m => String -> m OsString Source #
Partial unicode friendly encoding.
On windows this encodes as UTF16-LE (strictly), which is a pretty good guess. On unix this encodes as UTF8 (strictly), which is a good guess.
Throws an EncodingException
if encoding fails. If the input does not
contain surrogate chars, you can use unsafeEncodeUtf
.
unsafeEncodeUtf :: HasCallStack => String -> OsString Source #
Unsafe unicode friendly encoding.
Like encodeUtf
, except it crashes when the input contains
surrogate chars. For sanitized input, this can be useful.
Arguments
:: TextEncoding | unix text encoding |
-> TextEncoding | windows text encoding (wide char) |
-> String | |
-> Either EncodingException OsString |
Encode a FilePath
with the specified encoding.
Note: on windows, we expect a "wide char" encoding (e.g. UCS-2 or UTF-16). Anything
that works with Word16
boundaries. Picking an incompatible encoding may crash
filepath operations.
encodeFS :: String -> IO OsString Source #
Like encodeUtf
, except this mimics the behavior of the base library when doing filesystem
operations, which is:
- on unix, uses shady PEP 383 style encoding (based on the current locale, but PEP 383 only works properly on UTF-8 encodings, so good luck)
- on windows does permissive UTF-16 encoding, where coding errors generate Chars in the surrogate range
Looking up the locale requires IO. If you're not worried about calls
to setFileSystemEncoding
, then unsafePerformIO
may be feasible (make sure
to deeply evaluate the result to catch exceptions).
decodeUtf :: MonadThrow m => OsString -> m String Source #
Partial unicode friendly decoding.
On windows this decodes as UTF16-LE (strictly), which is a pretty good guess. On unix this decodes as UTF8 (strictly), which is a good guess. Note that filenames on unix are encoding agnostic char arrays.
Throws a EncodingException
if decoding fails.
Arguments
:: TextEncoding | unix text encoding |
-> TextEncoding | windows text encoding |
-> OsString | |
-> Either EncodingException String |
Decode an OsString
with the specified encoding.
The String is forced into memory to catch all exceptions.
decodeFS :: OsString -> IO String Source #
Like decodeUtf
, except this mimics the behavior of the base library when doing filesystem
operations, which is:
- on unix, uses shady PEP 383 style encoding (based on the current locale, but PEP 383 only works properly on UTF-8 encodings, so good luck)
- on windows does permissive UTF-16 encoding, where coding errors generate Chars in the surrogate range
Looking up the locale requires IO. If you're not worried about calls
to setFileSystemEncoding
, then unsafePerformIO
may be feasible (make sure
to deeply evaluate the result to catch exceptions).
fromBytes :: MonadThrow m => ByteString -> m OsString Source #
Constructs an OsString
from a ByteString.
On windows, this ensures valid UCS-2LE, on unix it is passed unchanged/unchecked.
Throws EncodingException
on invalid UCS-2LE on windows (although unlikely).
osstr :: QuasiQuoter Source #
QuasiQuote an OsString
. This accepts Unicode characters
and encodes as UTF-8 on unix and UTF-16 on windows.
If used as pattern, requires turning on the ViewPatterns
extension.
pack :: [OsChar] -> OsString Source #
Pack a list of OsChar
to an OsString
Note that using this in conjunction with unsafeFromChar
to
convert from [Char]
to OsString
is probably not what
you want, because it will truncate unicode code points.
unsafeFromChar :: Char -> OsChar Source #
Truncates on unix to 1 and on Windows to 2 octets.
snoc :: OsString -> OsChar -> OsString Source #
O(n) Append a byte to the end of a OsString
Since: os-string-1.4.200.0
cons :: OsChar -> OsString -> OsString Source #
O(n) cons
is analogous to (:) for lists.
Since: os-string-1.4.200.0
last :: HasCallStack => OsString -> OsChar Source #
O(1) Extract the last element of a OsString, which must be finite and non-empty. An exception will be thrown in the case of an empty OsString.
This is a partial function, consider using unsnoc
instead.
Since: os-string-1.4.200.0
tail :: HasCallStack => OsString -> OsString Source #
O(n) Extract the elements after the head of a OsString, which must be non-empty. An exception will be thrown in the case of an empty OsString.
This is a partial function, consider using uncons
instead.
Since: os-string-1.4.200.0
head :: HasCallStack => OsString -> OsChar Source #
O(1) Extract the first element of a OsString, which must be non-empty. An exception will be thrown in the case of an empty OsString.
This is a partial function, consider using uncons
instead.
Since: os-string-1.4.200.0
map :: (OsChar -> OsChar) -> OsString -> OsString Source #
O(n) map
f xs
is the OsString obtained by applying f
to each
element of xs
.
Since: os-string-1.4.200.0
reverse :: OsString -> OsString Source #
O(n) reverse
xs
efficiently returns the elements of xs
in reverse order.
Since: os-string-1.4.200.0
intercalate :: OsString -> [OsString] -> OsString Source #
O(n) The intercalate
function takes a OsString
and a list of
OsString
s and concatenates the list after interspersing the first
argument between each element of the list.
Since: os-string-1.4.200.0
foldl :: (a -> OsChar -> a) -> a -> OsString -> a Source #
foldl
, applied to a binary operator, a starting value (typically
the left-identity of the operator), and a OsString, reduces the
OsString using the binary operator, from left to right.
Since: os-string-1.4.200.0
foldr :: (OsChar -> a -> a) -> a -> OsString -> a Source #
foldr
, applied to a binary operator, a starting value
(typically the right-identity of the operator), and a OsString,
reduces the OsString using the binary operator, from right to left.
Since: os-string-1.4.200.0
replicate :: Int -> OsChar -> OsString Source #
O(n) replicate
n x
is a OsString of length n
with x
the value of every element. The following holds:
replicate w c = unfoldr w (\u -> Just (u,u)) c
Since: os-string-1.4.200.0
unfoldr :: (a -> Maybe (OsChar, a)) -> a -> OsString Source #
O(n), where n is the length of the result. The unfoldr
function is analogous to the List 'unfoldr'. unfoldr
builds a
OsString from a seed value. The function takes the element and
returns Nothing
if it is done producing the OsString or returns
Just
(a,b)
, in which case, a
is the next byte in the string,
and b
is the seed value for further production.
This function is not efficient/safe. It will build a list of [Word8]
and run the generator until it returns Nothing
, otherwise recurse infinitely,
then finally create a OsString
.
If you know the maximum length, consider using unfoldrN
.
Examples:
unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0 == pack [0, 1, 2, 3, 4, 5]
Since: os-string-1.4.200.0
unfoldrN :: Int -> (a -> Maybe (OsChar, a)) -> a -> (OsString, Maybe a) Source #
O(n) Like unfoldr
, unfoldrN
builds a OsString from a seed
value. However, the length of the result is limited by the first
argument to unfoldrN
. This function is more efficient than unfoldr
when the maximum length of the result is known.
The following equation relates unfoldrN
and unfoldr
:
fst (unfoldrN n f s) == take n (unfoldr f s)
Since: os-string-1.4.200.0
takeWhileEnd :: (OsChar -> Bool) -> OsString -> OsString Source #
Returns the longest (possibly empty) suffix of elements satisfying the predicate.
is equivalent to takeWhileEnd
p
.reverse
. takeWhile
p . reverse
Since: os-string-1.4.200.0
takeWhile :: (OsChar -> Bool) -> OsString -> OsString Source #
Similar to takeWhile
,
returns the longest (possibly empty) prefix of elements
satisfying the predicate.
Since: os-string-1.4.200.0
dropWhile :: (OsChar -> Bool) -> OsString -> OsString Source #
Similar to dropWhile
,
drops the longest (possibly empty) prefix of elements
satisfying the predicate and returns the remainder.
Since: os-string-1.4.200.0
dropWhileEnd :: (OsChar -> Bool) -> OsString -> OsString Source #
Similar to dropWhileEnd
,
drops the longest (possibly empty) suffix of elements
satisfying the predicate and returns the remainder.
is equivalent to dropWhileEnd
p
.reverse
. dropWhile
p . reverse
Since: os-string-1.4.200.0
breakEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString) Source #
Returns the longest (possibly empty) suffix of elements which do not satisfy the predicate and the remainder of the string.
breakEnd
p
is equivalent to
and to spanEnd
(not . p)(
.takeWhileEnd
(not . p) &&& dropWhileEnd
(not . p))
Since: os-string-1.4.200.0
spanEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString) Source #
Returns the longest (possibly empty) suffix of elements satisfying the predicate and the remainder of the string.
spanEnd
p
is equivalent to
and to breakEnd
(not . p)(
.takeWhileEnd
p &&& dropWhileEnd
p)
We have
spanEnd (not . isSpace) "x y z" == ("x y ", "z")
and
spanEnd (not . isSpace) sbs == let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
Since: os-string-1.4.200.0
split :: OsChar -> OsString -> [OsString] Source #
O(n) Break a OsString
into pieces separated by the byte
argument, consuming the delimiter. I.e.
split 10 "a\nb\nd\ne" == ["a","b","d","e"] -- fromEnum '\n' == 10 split 97 "aXaXaXa" == ["","X","X","X",""] -- fromEnum 'a' == 97 split 120 "x" == ["",""] -- fromEnum 'x' == 120 split undefined "" == [] -- and not [""]
and
intercalate [c] . split c == id split == splitWith . (==)
Since: os-string-1.4.200.0
splitWith :: (OsChar -> Bool) -> OsString -> [OsString] Source #
O(n) Splits a OsString
into components delimited by
separators, where the predicate returns True for a separator element.
The resulting components do not contain the separators. Two adjacent
separators result in an empty component in the output. eg.
splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97 splitWith undefined "" == [] -- and not [""]
Since: os-string-1.4.200.0
stripSuffix :: OsString -> OsString -> Maybe OsString Source #
O(n) The stripSuffix
function takes two OsStrings and returns Just
the remainder of the second iff the first is its suffix, and otherwise
Nothing
.
Since: os-string-1.4.200.0
stripPrefix :: OsString -> OsString -> Maybe OsString Source #
O(n) The stripPrefix
function takes two OsStrings and returns Just
the remainder of the second iff the first is its prefix, and otherwise
Nothing
.
Since: os-string-1.4.200.0
isInfixOf :: OsString -> OsString -> Bool Source #
Check whether one string is a substring of another.
Since: os-string-1.4.200.0
isPrefixOf :: OsString -> OsString -> Bool Source #
O(n) The isPrefixOf
function takes two OsStrings and returns True
Since: os-string-1.4.200.0
isSuffixOf :: OsString -> OsString -> Bool Source #
O(n) The isSuffixOf
function takes two OsStrings and returns True
iff the first is a suffix of the second.
The following holds:
isSuffixOf x y == reverse x `isPrefixOf` reverse y
Since: os-string-1.4.200.0
breakSubstring :: OsString -> OsString -> (OsString, OsString) Source #
Break a string on a substring, returning a pair of the part of the string prior to the match, and the rest of the string.
The following relationships hold:
break (== c) l == breakSubstring (singleton c) l
For example, to tokenise a string, dropping delimiters:
tokenise x y = h : if null t then [] else tokenise x (drop (length x) t) where (h,t) = breakSubstring x y
To skip to the first occurrence of a string:
snd (breakSubstring x y)
To take the parts of a string before a delimiter:
fst (breakSubstring x y)
Note that calling `breakSubstring x` does some preprocessing work, so you should avoid unnecessarily duplicating breakSubstring calls with the same pattern.
Since: os-string-1.4.200.0
filter :: (OsChar -> Bool) -> OsString -> OsString Source #
O(n) filter
, applied to a predicate and a OsString,
returns a OsString containing those characters that satisfy the
predicate.
Since: os-string-1.4.200.0
partition :: (OsChar -> Bool) -> OsString -> (OsString, OsString) Source #
O(n) The partition
function takes a predicate a OsString and returns
the pair of OsStrings with elements which do and do not satisfy the
predicate, respectively; i.e.,
partition p bs == (filter p sbs, filter (not . p) sbs)
Since: os-string-1.4.200.0
index :: HasCallStack => OsString -> Int -> OsChar Source #
O(1) OsString
index (subscript) operator, starting from 0.
Since: os-string-1.4.200.0
elemIndices :: OsChar -> OsString -> [Int] Source #
O(n) The elemIndices
function extends elemIndex
, by returning
the indices of all elements equal to the query element, in ascending order.
Since: os-string-1.4.200.0
count :: OsChar -> OsString -> Int Source #
count returns the number of times its argument appears in the OsString
Since: os-string-1.4.200.0
findIndices :: (OsChar -> Bool) -> OsString -> [Int] Source #
O(n) The findIndices
function extends findIndex
, by returning the
indices of all elements satisfying the predicate, in ascending order.
Since: os-string-1.4.200.0