BSD-3-Clause licensed by Adam Bergmark
Maintained by [email protected]
This version can be pinned in stack with:through-text-0.1.0.0@sha256:8372e9cc17dfc1773b0a0a2efa0087301efacae660e6885388f4be582894a5c0,1288

Module documentation for 0.1.0.0

through-text Build Status

This is a small package defining two typeclasses ToText and FromText. It’s meant to be used in normal cases where you have some control over data, hence UTF-8 is assumed for all types.

Currently supported packages are text, bytestring, and case-insensitive, and String from base of course!

You can define FromText instances that may fail as FromText (Maybe a).

There are alse type aliases StrictText, LazyByteString et.c. so you don’t need to import them yourself, it also makes code easier to read than if you import Text unqualified.

Conversions from bytestrings use lenientDecode which replaces invalid characters with U+FFFD.

There are identity instances for StrictText. They allow you to use throughText instead of toText and fromText when working with StrictText itself. It is not meant as an encouragement to use type class constraints such as ToText a => a -> IO () in function signatures, I instead recommend using the actual type you want.

Motivation

In practice I’ve found that most textual conversions I do are just to glue packages together. I either know or am satisfied with assuming that the encoding is UTF-8 and I don’t really care about the types involved.

We should be using Text as the default textual type instead of String. tostring together with Data.String.IsString otherwise accomplishes the same goal. A current advantage of using String is that you do not need to enable OverloadedStrings for literals.

Multi-parameter type classes easily leads to ambiguity and leads to O(n^2) instances if you want to convert between every type. string-conversions implements this idea with the benefit that you have to pay even less attention of what types you are converting.

In most use sites conversions are total, encoding this possibility in the type class leads to partial functions or the need to handle impossible failures. convertible throws an exception if a failure occurs.

I don’t want conversions from types just because they have a textual representation such as ToText Int - most types have one after all. It’s unclear whether you want a pretty printed or structually focused result. Show already suffers this conflict.

Will instances for great-package be added?

Only if it’s a popular library with no more than a couple of (new) dependencies. If you ask I will either accept or guarantee to do a major version bump should I change my mind (so you don’t need to depend on a minor version

For that reason I added [case-insensitive](https://www.haskell.org/package/case-insensitive), it’s a very useful package with only a one-module dependency (hashable).

When to avoid this library

If you don’t know the encoding you should explicitly use other libraries e.g. text-icu.

Changes

0.1.0.0

  • Initial release