Imports and pragmas

OverloadedStrings lets string literals have type Text:

{-# LANGUAGE OverloadedStrings #-}

Imports are most commonly qualified:

import qualified Data.Text as T
import Data.Text (Text)

import qualified Data.Text.IO as T             -- for putStrLn, etc
import qualified Data.Text.Encoding as T       -- for UTF8 encoding/decoding

Lazy variant:

import qualified Data.Text.Lazy as T
import Data.Text.Lazy (Text)

import qualified Data.Text.Lazy.IO as T        -- for putStrLn, etc
import qualified Data.Text.Lazy.Encoding as T  -- for UTF8 encoding/decoding

If you're not using anything like base-prelude, you might want to import Data.Monoid to have concatenation:

import Data.Monoid

Strict and lazy Text

There are 2 text types in the library – both are called Text but one comes from the Data.Text module and the other from Data.Text.Lazy module. They're not compatible (but you can convert between them), and are intended for use in different situations.

Strict Text is an array of characters. Lazy Text is a list (possibly infinite) of arrays of characters, or chunks. It's recommended to use lazy Text for cases where it makes sense to process text in a streaming fashion – for instance, if you have a huge file that you want to read and output as a web page, you could do it like “read a chunk, output a chunk, read a chunk, output a chunk...” – which is what might happen automatically if you use lazy Text correctly.

A rule of thumb is “if you don't ever intend for the string to be in memory only partially, use strict Text”.

To convert lazy Text to strict Text, use toStrict from Data.Text.Lazy; fromStrict goes in the opposite direction. To break a lazy Text into a list of chunks, use toChunks, and for the reverse – fromChunks.

Usage

Most functions from Prelude are replicated in Data.Text. The ones that are new are replicated below.

Common functions

• pack and unpack for converting between String and Text
• cons and snoc to prepend/append a character
• (<>) from Data.Monoid appends two strings
• toLower and toUpper convert to upper/lowercase (there's also `toTitle)
• toCaseFold is used for case-insensitive comparisons: toCaseFold x == toCaseFold y

Searching

replace x y replaces x by y:

> replace " " "_" "hello world"
"hello_world"

> replace "ofo" "bar" "ofofo"
"barfo"

breakOn splits the string into “before separator” and “after separator” parts, where separator can be a string; breakOnEnd does the same but starts from the end:

> breakOn "::" "a::b::c"
("a", "::b::c")

> breakOnEnd "::" "a::b::c"
("a::b::", "c")

breakOnAll gives you all splitting variants:

> breakOnAll "::" "a::b::c"
[("a", "::b::c"), ("a::b", "::c")]

splitOn splits the string into a list of strings; split breaks on predicate Char -> Bool:

> splitOn "::" "a::b::c"
["a","b","c"]

> split (not . isAlphaNum) "a::b::c"
["a","","b","","c"]

count counts how many times a string occurs in another string (without overlaps).

Cutting strings

take and takeEnd take N characters from the beginning/end, drop and dropEnd remove them.

takeWhile, takeWhileEnd, dropWhile and dropWhileEnd exist as well. dropAround strips characters from both sides of the string.

strip, stripStart and stripEnd strip spaces specifically.

stripPrefix and stripSuffix remove some particular prefix/suffix (or return Nothing). commonPrefixes takes two strings and cuts out the longest matching prefix from them.

chunksOf splits a string into chunks of length N.

Transformations

justifyRight and justifyLeft add characters to the beginning/end of the string until it reaches certain length:

> justifyRight 7 '_' "foo"
"____foo"

> justifyLeft 7 '_' "foo"
"foo____"

center adds the character to both sides equally, breaking ties in favor of the left side:

> center 7 '_' "foo"
"__foo__"

> center 8 '_' "foo"
"___foo__"

Optimisation

TODO: mention copy, Builder, explain how fusion works, etc.

FAQ

• Where is elem?

  It's been removed from text because you can use isInfixOf to do the same thing.
  Thanks to rewrite rules, T.isInfixOf "c" or T.isInfixOf (T.singleton c) will be as fast as elem.

Usage

Splitting

You can split strings into words and lines by using words/lines. However, for more options use the split package:

import Data.List.Split

Its documentation is actually pretty good, so it won't be replicated here.

Imports and pragmas

This module is the same as Data.ByteString but converts all bytes to characters without you having to do it:

import qualified Data.ByteString.Char8 as BC

And to be able to use string literals to construct ByteStrings, enable OverloadedStrings:

{-# LANGUAGE OverloadedStrings #-}

add something!

add something!

add something!