System.OsString.Windows

os-string-2.0.2: Library for manipulating Operating system strings.

Safe Haskell | None
Language | Haskell2010

System.OsString.Windows

Contents

- Types
- String construction
- String deconstruction
- Word construction
- Word deconstruction
- Basic interface
- Transforming OsString
- Reducing OsStrings (folds)
  - Special folds
  - Generating and unfolding OsStrings
- Substrings
  - Breaking strings
- Predicates
  - Search for arbitrary susbstrings
- Searching OsStrings
  - Searching by equality
- Indexing OsStrings

Synopsis

- data WindowsString
- data WindowsChar
- encodeUtf :: MonadThrow m => String -> m WindowsString
- unsafeEncodeUtf :: HasCallStack => String -> WindowsString
- encodeWith :: TextEncoding -> String -> Either EncodingException WindowsString
- encodeFS :: String -> IO WindowsString
- fromBytes :: MonadThrow m => ByteString -> m WindowsString
- pstr :: QuasiQuoter
- singleton :: WindowsChar -> WindowsString
- empty :: WindowsString
- pack :: [WindowsChar] -> WindowsString
- decodeUtf :: MonadThrow m => WindowsString -> m String
- decodeWith :: TextEncoding -> WindowsString -> Either EncodingException String
- decodeFS :: WindowsString -> IO String
- unpack :: WindowsString -> [WindowsChar]
- unsafeFromChar :: Char -> WindowsChar
- toChar :: WindowsChar -> Char
- snoc :: WindowsString -> WindowsChar -> WindowsString
- cons :: WindowsChar -> WindowsString -> WindowsString
- last :: HasCallStack => WindowsString -> WindowsChar
- tail :: HasCallStack => WindowsString -> WindowsString
- uncons :: WindowsString -> Maybe (WindowsChar, WindowsString)
- head :: HasCallStack => WindowsString -> WindowsChar
- init :: HasCallStack => WindowsString -> WindowsString
- unsnoc :: WindowsString -> Maybe (WindowsString, WindowsChar)
- null :: WindowsString -> Bool
- length :: WindowsString -> Int
- map :: (WindowsChar -> WindowsChar) -> WindowsString -> WindowsString
- reverse :: WindowsString -> WindowsString
- intercalate :: WindowsString -> [WindowsString] -> WindowsString
- foldl :: (a -> WindowsChar -> a) -> a -> WindowsString -> a
- foldl' :: (a -> WindowsChar -> a) -> a -> WindowsString -> a
- foldl1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
- foldl1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
- foldr :: (WindowsChar -> a -> a) -> a -> WindowsString -> a
- foldr' :: (WindowsChar -> a -> a) -> a -> WindowsString -> a
- foldr1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
- foldr1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
- all :: (WindowsChar -> Bool) -> WindowsString -> Bool
- any :: (WindowsChar -> Bool) -> WindowsString -> Bool
- concat :: [WindowsString] -> WindowsString
- replicate :: Int -> WindowsChar -> WindowsString
- unfoldr :: (a -> Maybe (WindowsChar, a)) -> a -> WindowsString
- unfoldrN :: Int -> (a -> Maybe (WindowsChar, a)) -> a -> (WindowsString, Maybe a)
- take :: Int -> WindowsString -> WindowsString
- takeEnd :: Int -> WindowsString -> WindowsString
- takeWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
- takeWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
- drop :: Int -> WindowsString -> WindowsString
- dropEnd :: Int -> WindowsString -> WindowsString
- dropWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
- dropWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
- break :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
- breakEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
- span :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
- spanEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
- splitAt :: Int -> WindowsString -> (WindowsString, WindowsString)
- split :: WindowsChar -> WindowsString -> [WindowsString]
- splitWith :: (WindowsChar -> Bool) -> WindowsString -> [WindowsString]
- stripSuffix :: WindowsString -> WindowsString -> Maybe WindowsString
- stripPrefix :: WindowsString -> WindowsString -> Maybe WindowsString
- isInfixOf :: WindowsString -> WindowsString -> Bool
- isPrefixOf :: WindowsString -> WindowsString -> Bool
- isSuffixOf :: WindowsString -> WindowsString -> Bool
- breakSubstring :: WindowsString -> WindowsString -> (WindowsString, WindowsString)
- elem :: WindowsChar -> WindowsString -> Bool
- find :: (WindowsChar -> Bool) -> WindowsString -> Maybe WindowsChar
- filter :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
- partition :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
- index :: HasCallStack => WindowsString -> Int -> WindowsChar
- indexMaybe :: WindowsString -> Int -> Maybe WindowsChar
- (!?) :: WindowsString -> Int -> Maybe WindowsChar
- elemIndex :: WindowsChar -> WindowsString -> Maybe Int
- elemIndices :: WindowsChar -> WindowsString -> [Int]
- count :: WindowsChar -> WindowsString -> Int
- findIndex :: (WindowsChar -> Bool) -> WindowsString -> Maybe Int
- findIndices :: (WindowsChar -> Bool) -> WindowsString -> [Int]

# Types

data WindowsString Source #

Commonly used windows string as wide character bytes.

#### Instances

Instances details

NFData WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Methods rnf :: WindowsString -> () Source #
Monoid WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Methods mempty :: WindowsString # mappend :: WindowsString -> WindowsString -> WindowsString # mconcat :: [WindowsString] -> WindowsString #
Semigroup WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Methods (<>) :: WindowsString -> WindowsString -> WindowsString # sconcat :: NonEmpty WindowsString -> WindowsString # stimes :: Integral b => b -> WindowsString -> WindowsString #
Generic WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Associated Types
type Rep WindowsString |
Instance details Defined in System.OsString.Internal.Types type Rep WindowsString = D1 ('MetaData "WindowsString" "System.OsString.Internal.Types" "os-string-2.0.2-ab18" 'True) (C1 ('MetaCons "WindowsString" 'PrefixI 'True) (S1 ('MetaSel ('Just "getWindowsString") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ShortByteString)))
Methods from :: WindowsString -> Rep WindowsString x # to :: Rep WindowsString x -> WindowsString #
Show WindowsString Source # | Decodes as UCS-2.
Instance details Defined in System.OsString.Internal.Types Methods showsPrec :: Int -> WindowsString -> ShowS # show :: WindowsString -> String # showList :: [WindowsString] -> ShowS #
Eq WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Methods (==) :: WindowsString -> WindowsString -> Bool # (/=) :: WindowsString -> WindowsString -> Bool #
Ord WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Methods compare :: WindowsString -> WindowsString -> Ordering # (<) :: WindowsString -> WindowsString -> Bool # (<=) :: WindowsString -> WindowsString -> Bool # (>) :: WindowsString -> WindowsString -> Bool # (>=) :: WindowsString -> WindowsString -> Bool # max :: WindowsString -> WindowsString -> WindowsString # min :: WindowsString -> WindowsString -> WindowsString #
Lift WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types Methods lift :: Quote m => WindowsString -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => WindowsString -> Code m WindowsString Source #
type Rep WindowsString Source # |
Instance details Defined in System.OsString.Internal.Types type Rep WindowsString = D1 ('MetaData "WindowsString" "System.OsString.Internal.Types" "os-string-2.0.2-ab18" 'True) (C1 ('MetaCons "WindowsString" 'PrefixI 'True) (S1 ('MetaSel ('Just "getWindowsString") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ShortByteString)))

data WindowsChar Source #

#### Instances

Instances details

NFData WindowsChar Source # |
Instance details Defined in System.OsString.Internal.Types Methods rnf :: WindowsChar -> () Source #
Generic WindowsChar Source # |
Instance details Defined in System.OsString.Internal.Types Associated Types
type Rep WindowsChar |
Instance details Defined in System.OsString.Internal.Types type Rep WindowsChar = D1 ('MetaData "WindowsChar" "System.OsString.Internal.Types" "os-string-2.0.2-ab18" 'True) (C1 ('MetaCons "WindowsChar" 'PrefixI 'True) (S1 ('MetaSel ('Just "getWindowsChar") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word16)))
Methods from :: WindowsChar -> Rep WindowsChar x # to :: Rep WindowsChar x -> WindowsChar #
Show WindowsChar Source # |
Instance details Defined in System.OsString.Internal.Types Methods showsPrec :: Int -> WindowsChar -> ShowS # show :: WindowsChar -> String # showList :: [WindowsChar] -> ShowS #
Eq WindowsChar Source # |
Instance details Defined in System.OsString.Internal.Types Methods (==) :: WindowsChar -> WindowsChar -> Bool # (/=) :: WindowsChar -> WindowsChar -> Bool #
Ord WindowsChar Source # |
Instance details Defined in System.OsString.Internal.Types Methods compare :: WindowsChar -> WindowsChar -> Ordering # (<) :: WindowsChar -> WindowsChar -> Bool # (<=) :: WindowsChar -> WindowsChar -> Bool # (>) :: WindowsChar -> WindowsChar -> Bool # (>=) :: WindowsChar -> WindowsChar -> Bool # max :: WindowsChar -> WindowsChar -> WindowsChar # min :: WindowsChar -> WindowsChar -> WindowsChar #
type Rep WindowsChar Source # |
Instance details Defined in System.OsString.Internal.Types type Rep WindowsChar = D1 ('MetaData "WindowsChar" "System.OsString.Internal.Types" "os-string-2.0.2-ab18" 'True) (C1 ('MetaCons "WindowsChar" 'PrefixI 'True) (S1 ('MetaSel ('Just "getWindowsChar") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word16)))

# String construction

encodeUtf :: MonadThrow m => String -> m WindowsString Source #

Partial unicode friendly encoding.

This encodes as UTF16-LE (strictly), which is a pretty good guess.

Throws an `EncodingException` if encoding fails. If the input does not contain surrogate chars, you can use `unsafeEncodeUtf`.

unsafeEncodeUtf :: HasCallStack => String -> WindowsString Source #

Unsafe unicode friendly encoding.

Like `encodeUtf`, except it crashes when the input contains surrogate chars. For sanitized input, this can be useful.

encodeWith :: TextEncoding -> String -> Either EncodingException WindowsString Source #

Encode a `String` with the specified encoding.

encodeFS :: String -> IO WindowsString Source #

This mimics the behavior of the base library when doing filesystem operations, which does permissive UTF-16 encoding, where coding errors generate Chars in the surrogate range.

The reason this is in IO is because it unifies with the Posix counterpart, which does require IO. This is safe to `unsafePerformIO`/`unsafeDupablePerformIO`.

fromBytes :: MonadThrow m => ByteString -> m WindowsString Source #

Constructs a platform string from a ByteString.

This ensures valid UCS-2LE. Note that this doesn't expand Word8 to Word16 on windows, so you may get invalid UTF-16.

Throws `EncodingException` on invalid UCS-2LE (although unlikely).

pstr :: QuasiQuoter Source #

QuasiQuote a `WindowsString`. This accepts Unicode characters and encodes as UTF-16LE on windows.

singleton :: WindowsChar -> WindowsString Source #

empty :: WindowsString Source #

pack :: [WindowsChar] -> WindowsString Source #

Pack a list of platform words to a platform string.

Note that using this in conjunction with `unsafeFromChar` to convert from `[Char]` to platform string is probably not what you want, because it will truncate unicode code points.

# String deconstruction

decodeUtf :: MonadThrow m => WindowsString -> m String Source #

Partial unicode friendly decoding.

This decodes as UTF16-LE (strictly), which is a pretty good.

Throws a `EncodingException` if decoding fails.

decodeWith :: TextEncoding -> WindowsString -> Either EncodingException String Source #

Decode a `WindowsString` with the specified encoding.

The String is forced into memory to catch all exceptions.

decodeFS :: WindowsString -> IO String Source #

Like `decodeUtf`, except this mimics the behavior of the base library when doing filesystem operations, which does permissive UTF-16 encoding, where coding errors generate Chars in the surrogate range.

The reason this is in IO is because it unifies with the Posix counterpart, which does require IO. `unsafePerformIO`/`unsafeDupablePerformIO` are safe, however.

unpack :: WindowsString -> [WindowsChar] Source #

Unpack a platform string to a list of platform words.

# Word construction

unsafeFromChar :: Char -> WindowsChar Source #

Truncates to 2 octets.

# Word deconstruction

toChar :: WindowsChar -> Char Source #

Converts back to a unicode codepoint (total).

# Basic interface

snoc :: WindowsString -> WindowsChar -> WindowsString Source #

O(n) Append a byte to the end of a `OsString`

Since: os-string-1.4.200.0

cons :: WindowsChar -> WindowsString -> WindowsString Source #

O(n) `cons` is analogous to (:) for lists.

Since: os-string-1.4.200.0

last :: HasCallStack => WindowsString -> WindowsChar 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 => WindowsString -> WindowsString 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

uncons :: WindowsString -> Maybe (WindowsChar, WindowsString) Source #

O(n) Extract the `head` and `tail` of a OsString, returning `Nothing` if it is empty.

Since: os-string-1.4.200.0

head :: HasCallStack => WindowsString -> WindowsChar 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

init :: HasCallStack => WindowsString -> WindowsString Source #

O(n) Return all the elements of a `OsString` except the last one. 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

unsnoc :: WindowsString -> Maybe (WindowsString, WindowsChar) Source #

O(n) Extract the `init` and `last` of a OsString, returning `Nothing` if it is empty.

Since: os-string-1.4.200.0

null :: WindowsString -> Bool Source #

O(1). The empty `OsString`.

Since: os-string-1.4.200.0

length :: WindowsString -> Int Source #

O(1) The length of a `OsString`.

Since: os-string-1.4.200.0

# Transforming OsString

map :: (WindowsChar -> WindowsChar) -> WindowsString -> WindowsString 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 :: WindowsString -> WindowsString Source #

O(n) `reverse` `xs` efficiently returns the elements of `xs` in reverse order.

Since: os-string-1.4.200.0

intercalate :: WindowsString -> [WindowsString] -> WindowsString 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

# Reducing OsStrings (folds)

foldl :: (a -> WindowsChar -> a) -> a -> WindowsString -> 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

foldl' :: (a -> WindowsChar -> a) -> a -> WindowsString -> a Source #

`foldl'` is like `foldl`, but strict in the accumulator.

Since: os-string-1.4.200.0

foldl1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar Source #

`foldl1` is a variant of `foldl` that has no starting value argument, and thus must be applied to non-empty `OsString`s. An exception will be thrown in the case of an empty OsString.

Since: os-string-1.4.200.0

foldl1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar Source #

`foldl1'` is like `foldl1`, but strict in the accumulator. An exception will be thrown in the case of an empty OsString.

Since: os-string-1.4.200.0

foldr :: (WindowsChar -> a -> a) -> a -> WindowsString -> 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

foldr' :: (WindowsChar -> a -> a) -> a -> WindowsString -> a Source #

`foldr'` is like `foldr`, but strict in the accumulator.

Since: os-string-1.4.200.0

foldr1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar Source #

`foldr1` is a variant of `foldr` that has no starting value argument, and thus must be applied to non-empty `OsString`s An exception will be thrown in the case of an empty OsString.

Since: os-string-1.4.200.0

foldr1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar Source #

`foldr1'` is a variant of `foldr1`, but is strict in the accumulator.

Since: os-string-1.4.200.0

## Special folds

all :: (WindowsChar -> Bool) -> WindowsString -> Bool Source #

O(n) Applied to a predicate and a `OsString`, `all` determines if all elements of the `OsString` satisfy the predicate.

Since: os-string-1.4.200.0

any :: (WindowsChar -> Bool) -> WindowsString -> Bool Source #

O(n) Applied to a predicate and a `OsString`, `any` determines if any element of the `OsString` satisfies the predicate.

Since: os-string-1.4.200.0

concat :: [WindowsString] -> WindowsString Source #

## Generating and unfolding OsStrings

replicate :: Int -> WindowsChar -> WindowsString 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 (WindowsChar, a)) -> a -> WindowsString 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 (WindowsChar, a)) -> a -> (WindowsString, 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

# Substrings

## Breaking strings

take :: Int -> WindowsString -> WindowsString Source #

O(n) `take` `n`, applied to a OsString `xs`, returns the prefix of `xs` of length `n`, or `xs` itself if `n > `length` xs`.

Since: os-string-1.4.200.0

takeEnd :: Int -> WindowsString -> WindowsString Source #

O(n) ``takeEnd` n xs` is equivalent to ``drop` (`length` xs - n) xs`. Takes `n` elements from end of bytestring.

    >>> takeEnd 3 "abcdefg"
    "efg"
    >>> takeEnd 0 "abcdefg"
    ""
    >>> takeEnd 4 "abc"
    "abc"

Since: os-string-1.4.200.0

takeWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString Source #

Returns the longest (possibly empty) suffix of elements satisfying the predicate.

``takeWhileEnd` p` is equivalent to ``reverse` . `takeWhile` p . `reverse``.

Since: os-string-1.4.200.0

takeWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString Source #

Similar to `takeWhile`, returns the longest (possibly empty) prefix of elements satisfying the predicate.

Since: os-string-1.4.200.0

drop :: Int -> WindowsString -> WindowsString Source #

O(n) `drop` `n` `xs` returns the suffix of `xs` after the first n elements, or `empty` if `n > `length` xs`.

Since: os-string-1.4.200.0

dropEnd :: Int -> WindowsString -> WindowsString Source #

O(n) ``dropEnd` n xs` is equivalent to ``take` (`length` xs - n) xs`. Drops `n` elements from end of bytestring.

    >>> dropEnd 3 "abcdefg"
    "abcd"
    >>> dropEnd 0 "abcdefg"
    "abcdefg"
    >>> dropEnd 4 "abc"
    ""

Since: os-string-1.4.200.0

dropWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString Source #

Similar to `dropWhileEnd`, drops the longest (possibly empty) suffix of elements satisfying the predicate and returns the remainder.

``dropWhileEnd` p` is equivalent to ``reverse` . `dropWhile` p . `reverse``.

Since: os-string-1.4.200.0

dropWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString 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

break :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString) Source #

Similar to `break`, returns the longest (possibly empty) prefix of elements which do not satisfy the predicate and the remainder of the string.

`break` `p` is equivalent to ``span` (not . p)` and to `(`takeWhile` (not . p) &&& `dropWhile` (not . p))`.

Since: os-string-1.4.200.0

breakEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString) 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 ``spanEnd` (not . p)` and to `(`takeWhileEnd` (not . p) &&& `dropWhileEnd` (not . p))`.

Since: os-string-1.4.200.0

span :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString) Source #

Similar to `span`, returns the longest (possibly empty) prefix of elements satisfying the predicate and the remainder of the string.

`span` `p` is equivalent to ``break` (not . p)` and to `(`takeWhile` p &&& `dropWhile` p)`.

Since: os-string-1.4.200.0

spanEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString) Source #

Returns the longest (possibly empty) suffix of elements satisfying the predicate and the remainder of the string.

`spanEnd` `p` is equivalent to ``breakEnd` (not . p)` and to `(`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

splitAt :: Int -> WindowsString -> (WindowsString, WindowsString) Source #

O(n) `splitAt` `n sbs` is equivalent to `(`take` n sbs, `drop` n sbs)`.

Since: os-string-1.4.200.0

split :: WindowsChar -> WindowsString -> [WindowsString] 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 :: (WindowsChar -> Bool) -> WindowsString -> [WindowsString] 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 :: WindowsString -> WindowsString -> Maybe WindowsString 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 :: WindowsString -> WindowsString -> Maybe WindowsString 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

# Predicates

isInfixOf :: WindowsString -> WindowsString -> Bool Source #

Check whether one string is a substring of another.

Since: os-string-1.4.200.0

isPrefixOf :: WindowsString -> WindowsString -> Bool Source #

O(n) The `isPrefixOf` function takes two OsStrings and returns `True`

Since: os-string-1.4.200.0

isSuffixOf :: WindowsString -> WindowsString -> 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

## Search for arbitrary susbstrings

breakSubstring :: WindowsString -> WindowsString -> (WindowsString, WindowsString) 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

# Searching OsStrings

## Searching by equality

elem :: WindowsChar -> WindowsString -> Bool Source #

O(n) `elem` is the `OsString` membership predicate.

Since: os-string-1.4.200.0

find :: (WindowsChar -> Bool) -> WindowsString -> Maybe WindowsChar Source #

O(n) The `find` function takes a predicate and a OsString, and returns the first element in matching the predicate, or `Nothing` if there is no such element.

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

Since: os-string-1.4.200.0

filter :: (WindowsChar -> Bool) -> WindowsString -> WindowsString 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 :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString) 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

# Indexing OsStrings

index :: HasCallStack => WindowsString -> Int -> WindowsChar Source #

O(1) `OsString` index (subscript) operator, starting from 0.

Since: os-string-1.4.200.0

indexMaybe :: WindowsString -> Int -> Maybe WindowsChar Source #

O(1) `OsString` index, starting from 0, that returns `Just` if:

    0 <= n < length bs

Since: os-string-1.4.200.0

(!?) :: WindowsString -> Int -> Maybe WindowsChar Source #

O(1) `OsString` index, starting from 0, that returns `Just` if:

    0 <= n < length bs

Since: os-string-1.4.200.0

elemIndex :: WindowsChar -> WindowsString -> Maybe Int Source #

O(n) The `elemIndex` function returns the index of the first element in the given `OsString` which is equal to the query element, or `Nothing` if there is no such element.

Since: os-string-1.4.200.0

elemIndices :: WindowsChar -> WindowsString -> [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 :: WindowsChar -> WindowsString -> Int Source #

count returns the number of times its argument appears in the OsString

Since: os-string-1.4.200.0

findIndex :: (WindowsChar -> Bool) -> WindowsString -> Maybe Int Source #

O(n) The `findIndex` function takes a predicate and a `OsString` and returns the index of the first element in the OsString satisfying the predicate.

Since: os-string-1.4.200.0

findIndices :: (WindowsChar -> Bool) -> WindowsString -> [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