Foundation.String

foundation-0.0.30: Alternative prelude with batteries and no dependencies

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | portable
Safe Haskell | None
Language | Haskell2010

Foundation.String

Description

Opaque packed String encoded in UTF8.

The type is an instance of IsString and IsList, which allow OverloadedStrings for string literal, and `fromList` to convert a [Char] (Prelude String) to a packed representation

    {-# LANGUAGE OverloadedStrings #-}
    s = "Hello World" :: String

    s = fromList ("Hello World" :: Prelude.String) :: String

Each unicode code point is represented by a variable encoding of 1 to 4 bytes,

For more information about UTF8: https://en.wikipedia.org/wiki/UTF-8

Synopsis

- data String
- data Encoding
  - = ASCII7
  - | UTF8
  - | UTF16
  - | UTF32
  - | ISO_8859_1
- fromBytes :: Encoding -> UArray Word8 -> (String, Maybe ValidationFailure, UArray Word8)
- fromBytesLenient :: UArray Word8 -> (String, UArray Word8)
- fromBytesUnsafe :: UArray Word8 -> String
- toBytes :: Encoding -> String -> UArray Word8
- data ValidationFailure
  - = InvalidHeader
  - | InvalidContinuation
  - | MissingByte
  - | BuildingFailure
- lines :: String -> [String]
- words :: String -> [String]
- upper :: String -> String
- lower :: String -> String
- replace :: String -> String -> String -> String
- indices :: String -> String -> [Offset8]
- toBase64 :: String -> String
- toBase64URL :: Bool -> String -> String
- toBase64OpenBSD :: String -> String
- breakLine :: String -> Either Bool (String, String)

# Documentation

data String #

Opaque packed array of characters in the UTF8 encoding

#### Instances

Instances details

NormalForm String |
Instance details Defined in Basement.UTF8.Base Methods toNormalForm :: String -> () #
Arbitrary String # |
Instance details Defined in Foundation.Check.Arbitrary Methods arbitrary :: Gen String #
Buildable String # |
Instance details Defined in Foundation.Collection.Buildable Associated Types
type Mutable String |
Instance details Defined in Foundation.Collection.Buildable type Mutable String = MutableString
type Step String |
Instance details Defined in Foundation.Collection.Buildable type Step String = Word8
Methods append :: forall (prim :: Type -> Type) err. PrimMonad prim => Element String -> Builder String (Mutable String) (Step String) prim err () # build :: PrimMonad prim => Int -> Builder String (Mutable String) (Step String) prim err () -> prim (Either err String) #
Collection String # |
Instance details Defined in Foundation.Collection.Collection Methods null :: String -> Bool # length :: String -> CountOf (Element String) # elem :: (Eq a, a ~ Element String) => Element String -> String -> Bool # notElem :: (Eq a, a ~ Element String) => Element String -> String -> Bool # maximum :: (Ord a, a ~ Element String) => NonEmpty String -> Element String # minimum :: (Ord a, a ~ Element String) => NonEmpty String -> Element String # any :: (Element String -> Bool) -> String -> Bool # all :: (Element String -> Bool) -> String -> Bool #
Copy String # |
Instance details Defined in Foundation.Collection.Copy Methods copy :: String -> String #
IndexedCollection String # |
Instance details Defined in Foundation.Collection.Indexed Methods (!) :: String -> Offset (Element String) -> Maybe (Element String) # findIndex :: (Element String -> Bool) -> String -> Maybe (Offset (Element String)) #
InnerFunctor String # |
Instance details Defined in Foundation.Collection.InnerFunctor Methods imap :: (Element String -> Element String) -> String -> String #
Sequential String # |
Instance details Defined in Foundation.Collection.Sequential Methods take :: CountOf (Element String) -> String -> String # revTake :: CountOf (Element String) -> String -> String # drop :: CountOf (Element String) -> String -> String # revDrop :: CountOf (Element String) -> String -> String # splitAt :: CountOf (Element String) -> String -> (String, String) # revSplitAt :: CountOf (Element String) -> String -> (String, String) # splitOn :: (Element String -> Bool) -> String -> [String] # break :: (Element String -> Bool) -> String -> (String, String) # breakEnd :: (Element String -> Bool) -> String -> (String, String) # breakElem :: Element String -> String -> (String, String) # takeWhile :: (Element String -> Bool) -> String -> String # dropWhile :: (Element String -> Bool) -> String -> String # intersperse :: Element String -> String -> String # intercalate :: Element String -> String -> Element String # span :: (Element String -> Bool) -> String -> (String, String) # spanEnd :: (Element String -> Bool) -> String -> (String, String) # filter :: (Element String -> Bool) -> String -> String # partition :: (Element String -> Bool) -> String -> (String, String) # reverse :: String -> String # uncons :: String -> Maybe (Element String, String) # unsnoc :: String -> Maybe (String, Element String) # snoc :: String -> Element String -> String # cons :: Element String -> String -> String # find :: (Element String -> Bool) -> String -> Maybe (Element String) # sortBy :: (Element String -> Element String -> Ordering) -> String -> String # singleton :: Element String -> String # head :: NonEmpty String -> Element String # last :: NonEmpty String -> Element String # tail :: NonEmpty String -> String # init :: NonEmpty String -> String # replicate :: CountOf (Element String) -> Element String -> String # isPrefixOf :: String -> String -> Bool # isSuffixOf :: String -> String -> Bool # isInfixOf :: String -> String -> Bool # stripPrefix :: String -> String -> Maybe String # stripSuffix :: String -> String -> Maybe String #
Zippable String # |
Instance details Defined in Foundation.Collection.Zippable Methods zipWith :: (Sequential a, Sequential b) => (Element a -> Element b -> Element String) -> a -> b -> String # zipWith3 :: (Sequential a, Sequential b, Sequential c) => (Element a -> Element b -> Element c -> Element String) -> a -> b -> c -> String # zipWith4 :: (Sequential a, Sequential b, Sequential c, Sequential d) => (Element a -> Element b -> Element c -> Element d -> Element String) -> a -> b -> c -> d -> String # zipWith5 :: (Sequential a, Sequential b, Sequential c, Sequential d, Sequential e) => (Element a -> Element b -> Element c -> Element d -> Element e -> Element String) -> a -> b -> c -> d -> e -> String # zipWith6 :: (Sequential a, Sequential b, Sequential c, Sequential d, Sequential e, Sequential f) => (Element a -> Element b -> Element c -> Element d -> Element e -> Element f -> Element String) -> a -> b -> c -> d -> e -> f -> String # zipWith7 :: (Sequential a, Sequential b, Sequential c, Sequential d, Sequential e, Sequential f, Sequential g) => (Element a -> Element b -> Element c -> Element d -> Element e -> Element f -> Element g -> Element String) -> a -> b -> c -> d -> e -> f -> g -> String #
IsField String # |
Instance details Defined in Foundation.Format.CSV.Types Methods toField :: String -> Field # fromField :: Field -> Either String String #
Hashable String # |
Instance details Defined in Foundation.Hashing.Hashable Methods hashMix :: Hasher st => String -> st -> st #
ParserSource String # |
Instance details Defined in Foundation.Parser Associated Types
type Chunk String |
Instance details Defined in Foundation.Parser type Chunk String = String
Methods nullChunk :: String -> Chunk String -> Bool # appendChunk :: String -> Chunk String -> String # subChunk :: String -> Offset (Element String) -> CountOf (Element String) -> Chunk String # spanChunk :: String -> Offset (Element String) -> (Element String -> Bool) -> (Chunk String, Offset (Element String)) #
Monoid String |
Instance details Defined in Basement.UTF8.Base Methods mempty :: String # mappend :: String -> String -> String # mconcat :: [String] -> String #
Semigroup String |
Instance details Defined in Basement.UTF8.Base Methods (<>) :: String -> String -> String # sconcat :: NonEmpty String -> String # stimes :: Integral b => b -> String -> String #
Data String |
Instance details Defined in Basement.UTF8.Base Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> String -> c String # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c String # toConstr :: String -> Constr # dataTypeOf :: String -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c String) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c String) # gmapT :: (forall b. Data b => b -> b) -> String -> String # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> String -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> String -> r # gmapQ :: (forall d. Data d => d -> u) -> String -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> String -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> String -> m String # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> String -> m String # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> String -> m String #
IsString String |
Instance details Defined in Basement.UTF8.Base Methods fromString :: String -> String #
IsList String |
Instance details Defined in Basement.UTF8.Base Associated Types
type Item String |
Instance details Defined in Basement.UTF8.Base type Item String = Char
Methods fromList :: [Item String] -> String # fromListN :: Int -> [Item String] -> String # toList :: String -> [Item String] #
Show String |
Instance details Defined in Basement.UTF8.Base Methods showsPrec :: Int -> String -> ShowS # show :: String -> String # showList :: [String] -> ShowS #
Eq String |
Instance details Defined in Basement.UTF8.Base Methods (==) :: String -> String -> Bool # (/=) :: String -> String -> Bool #
Ord String |
Instance details Defined in Basement.UTF8.Base Methods compare :: String -> String -> Ordering # (<) :: String -> String -> Bool # (<=) :: String -> String -> Bool # (>) :: String -> String -> Bool # (>=) :: String -> String -> Bool # max :: String -> String -> String # min :: String -> String -> String #
From AsciiString String |
Instance details Defined in Basement.From Methods from :: AsciiString -> String #
From String (UArray Word8) |
Instance details Defined in Basement.From Methods from :: String -> UArray Word8 #
Show (ParseError String) # |
Instance details Defined in Foundation.Parser Methods showsPrec :: Int -> ParseError String -> ShowS # show :: ParseError String -> String # showList :: [ParseError String] -> ShowS #
TryFrom (UArray Word8) String |
Instance details Defined in Basement.From Methods tryFrom :: UArray Word8 -> Maybe String #
IsProperty (String, Bool) # |
Instance details Defined in Foundation.Check.Property Methods property :: (String, Bool) -> Property #
type Mutable String # |
Instance details Defined in Foundation.Collection.Buildable type Mutable String = MutableString
type Step String # |
Instance details Defined in Foundation.Collection.Buildable type Step String = Word8
type Element String # |
Instance details Defined in Foundation.Collection.Element type Element String = Char
type Chunk String # |
Instance details Defined in Foundation.Parser type Chunk String = String
type Item String |
Instance details Defined in Basement.UTF8.Base type Item String = Char

data Encoding #

Various String Encoding that can be use to convert to and from bytes

Constructors

ASCII7 |
UTF8 |
UTF16 |
UTF32 |
ISO_8859_1 |

#### Instances

Instances details

Data Encoding |
Instance details Defined in Basement.String Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Encoding -> c Encoding # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Encoding # toConstr :: Encoding -> Constr # dataTypeOf :: Encoding -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Encoding) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Encoding) # gmapT :: (forall b. Data b => b -> b) -> Encoding -> Encoding # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Encoding -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Encoding -> r # gmapQ :: (forall d. Data d => d -> u) -> Encoding -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Encoding -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Encoding -> m Encoding # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Encoding -> m Encoding # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Encoding -> m Encoding #
Bounded Encoding |
Instance details Defined in Basement.String Methods minBound :: Encoding # maxBound :: Encoding #
Enum Encoding |
Instance details Defined in Basement.String Methods succ :: Encoding -> Encoding # pred :: Encoding -> Encoding # toEnum :: Int -> Encoding # fromEnum :: Encoding -> Int # enumFrom :: Encoding -> [Encoding] # enumFromThen :: Encoding -> Encoding -> [Encoding] # enumFromTo :: Encoding -> Encoding -> [Encoding] # enumFromThenTo :: Encoding -> Encoding -> Encoding -> [Encoding] #
Show Encoding |
Instance details Defined in Basement.String Methods showsPrec :: Int -> Encoding -> ShowS # show :: Encoding -> String # showList :: [Encoding] -> ShowS #
Eq Encoding |
Instance details Defined in Basement.String Methods (==) :: Encoding -> Encoding -> Bool # (/=) :: Encoding -> Encoding -> Bool #
Ord Encoding |
Instance details Defined in Basement.String Methods compare :: Encoding -> Encoding -> Ordering # (<) :: Encoding -> Encoding -> Bool # (<=) :: Encoding -> Encoding -> Bool # (>) :: Encoding -> Encoding -> Bool # (>=) :: Encoding -> Encoding -> Bool # max :: Encoding -> Encoding -> Encoding # min :: Encoding -> Encoding -> Encoding #

fromBytes :: Encoding -> UArray Word8 -> (String, Maybe ValidationFailure, UArray Word8) #

Convert a ByteArray to a string assuming a specific encoding.

It returns a 3-tuple of:

- The string that has been succesfully converted without any error
- An optional validation error
- The remaining buffer that hasn't been processed (either as a result of an error, or because the encoded sequence is not fully available)

Considering a stream of data that is fetched chunk by chunk, it's valid to assume that some sequence might fall in a chunk boundary. When converting chunks, if the error is Nothing and the remaining buffer is not empty, then this buffer need to be prepended to the next chunk

fromBytesLenient :: UArray Word8 -> (String, UArray Word8) #

Convert a UTF8 array of bytes to a String.

If there's any error in the stream, it will automatically insert replacement bytes to replace invalid sequences.

In the case of sequence that fall in the middle of 2 chunks, the remaining buffer is supposed to be preprended to the next chunk, and resume the parsing.

fromBytesUnsafe :: UArray Word8 -> String #

Convert a Byte Array representing UTF8 data directly to a string without checking for UTF8 validity

If the input contains invalid sequences, it will trigger runtime async errors when processing data.

In doubt, use `fromBytes`

toBytes :: Encoding -> String -> UArray Word8 #

Convert a String to a bytearray in a specific encoding

if the encoding is UTF8, the underlying buffer is returned without extra allocation or any processing

In any other encoding, some allocation and processing are done to convert.

data ValidationFailure #

Possible failure related to validating bytes of UTF8 sequences.

Constructors

InvalidHeader |
InvalidContinuation |
MissingByte |
BuildingFailure |

#### Instances

Instances details

Exception ValidationFailure |
Instance details Defined in Basement.UTF8.Types Methods toException :: ValidationFailure -> SomeException # fromException :: SomeException -> Maybe ValidationFailure # displayException :: ValidationFailure -> String # backtraceDesired :: ValidationFailure -> Bool #
Show ValidationFailure |
Instance details Defined in Basement.UTF8.Types Methods showsPrec :: Int -> ValidationFailure -> ShowS # show :: ValidationFailure -> String # showList :: [ValidationFailure] -> ShowS #
Eq ValidationFailure |
Instance details Defined in Basement.UTF8.Types Methods (==) :: ValidationFailure -> ValidationFailure -> Bool # (/=) :: ValidationFailure -> ValidationFailure -> Bool #

lines :: String -> [String] #

Split lines in a string using newline as separation.

Note that carriage return preceding a newline are also strip for maximum compatibility between Windows and Unix system.

words :: String -> [String] #

Split words in a string using spaces as separation

    words "Hello Foundation"

Hello, Foundation

upper :: String -> String #

Convert a `String` to the upper-case equivalent.

lower :: String -> String #

Convert a `String` to the upper-case equivalent.

replace :: String -> String -> String -> String #

Replace all the occurrencies of `needle` with `replacement` in the `haystack` string.

indices :: String -> String -> [Offset8] #

Finds where are the insertion points when we search for a `needle` within an `haystack`.

toBase64 :: String -> String #

Transform string `src` to base64 binary representation.

toBase64URL :: Bool -> String -> String #

Transform string `src` to URL-safe base64 binary representation. The result will be either padded or unpadded, depending on the boolean `padded` argument.

toBase64OpenBSD :: String -> String #

Transform string `src` to OpenBSD base64 binary representation.

breakLine :: String -> Either Bool (String, String) #

Same as break but cut on a line feed with an optional carriage return.

This is the same operation as 'breakElem LF' dropping the last character of the string if it's a CR.

Also for efficiency reason (streaming), it returns if the last character was a CR character.