core-text 0.3.7.1 → 0.3.7.2

raw patch · 4 files changed

+26/−24 lines, 4 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• core-text.cabal +1/−1
• lib/Core/Text/Bytes.hs +4/−4
• lib/Core/Text/Rope.hs +20/−18
• lib/Core/Text/Utilities.hs +1/−1

@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           core-text-version:        0.3.7.1+version:        0.3.7.2 synopsis:       A rope type based on a finger tree over UTF-8 fragments description:    A rope data type for text, built as a finger tree over UTF-8 text                 fragments. The package also includes utiltiy functions for breaking and

@@ -61,7 +61,7 @@     deriving (Show, Eq, Ord, Generic)  {- |-Access the strict 'ByteString' underlying the @Bytes@ type.+Access the strict 'Data.ByteString.ByteString' underlying the 'Bytes' type. -} unBytes :: Bytes -> B.ByteString unBytes (StrictBytes b') = b'@@ -119,11 +119,11 @@ For the annoyingly common case of needing to take an ASCII string literal in your code and use it as a bunch of 'Bytes'. -Done via "Data.ByteString.Char8" so all @Char@s will be truncated to 8 bits+Done via "Data.ByteString.Char8" so all 'Char's will be truncated to 8 bits (/i.e./ Latin-1 characters less than 255). You should probably consider this to be unsafe. Also note that we deliberately do not have a @[Char]@ instance of 'Binary'; if you need to come back to a textual representation use-'intoRope'.+'Core.Text.Rope.intoRope'. -} packBytes :: String -> Bytes packBytes = StrictBytes . C.pack@@ -143,7 +143,7 @@ ordering of output on the user's terminal. Instead do:  @-    'Core.Program.Execute.write' ('intoRope' b)+    'Core.Program.Execute.write' ('Core.Text.Rope.intoRope' b) @  on the assumption that the bytes in question are UTF-8 (or plain ASCII)

@@ -39,11 +39,13 @@  The second way is through the opaque @Text@ type of "Data.Text" from the __text__ package, which is well tuned and high-performing but suffers from the-same design; it is likewise backed by arrays. Rather surprisingly, the storage-backing Text objects are encoded in UTF-16, meaning every time you want to+same design; it is likewise backed by arrays. (Historically, the storage+backing Text objects was encoded in UTF-16, meaning every time you wanted to work with unicode characters that came in from /anywhere/ else and which-inevitably are UTF-8 encoded you have to convert to UTF-16 and copy into a new-array, wasting time and memory.+inevitably were UTF-8 encoded they had to be converted to UTF-16 and copied+into a further new array! Fortunately Haskell has recently adopted a UTF-8+backed @Text@ type, reducing this overhead. The challenge of appending pinned+allocations remains, however.)  In this package we introduce 'Rope', a text type backed by the 2-3 'Data.FingerTree.FingerTree' data structure from the __fingertree__ package.@@ -453,11 +455,11 @@ /Warning/  This function was necessary to have a reliable 'Hashable' instance. Currently-constructing this new @Rope@ is quite inefficient if the number of pieces or-their respective lengths are large. Usually, however, we're calling 'hash' so-the value can be used as a key in a hash table and such keys are typically-simple (or at least not ridiculously long), so this is not an issue in normal-usage.+constructing this new 'Rope' is quite inefficient if the number of pieces or+their respective lengths are large. Usually, however, we're calling+'Data.Hashable.hash' so the value can be used as a key in a hash table and+such keys are typically simple (or at least not ridiculously long), so this is+not an issue in normal usage. -} copyRope :: Rope -> Rope copyRope text@(Rope x) =@@ -471,21 +473,21 @@  {- | Machinery to interpret a type as containing valid Unicode that can be-represented as a @Rope@ object.+represented as a 'Rope' object.  /Implementation notes/ -Given that @Rope@ is backed by a finger tree, 'append' is relatively+Given that 'Rope' is backed by a finger tree, 'appendRope' is relatively inexpensive, plus whatever the cost of conversion is. There is a subtle trap, however: if adding small fragments of that were obtained by slicing (for-example) a large ByteString we would end up holding on to a reference to the-entire underlying block of memory. This module is optimized to reduce heap-fragmentation by letting the Haskell runtime and garbage collector manage the-memory, so instances are expected to /copy/ these substrings out of pinned-memory.+example) a large 'Data.ByteString.ByteString' we would end up holding on to a+reference to the entire underlying block of memory. This module is optimized+to reduce heap fragmentation by letting the Haskell runtime and garbage+collector manage the memory, so instances are expected to /copy/ these+substrings out of pinned memory. -The @ByteString@ instance requires that its content be valid UTF-8. If not an-empty @Rope@ will be returned.+The 'Data.ByteString.ByteString' instance requires that its content be valid+UTF-8. If not an empty 'Rope' will be returned.  Several of the 'fromRope' implementations are expensive and involve a lot of intermediate allocation and copying. If you're ultimately writing to a handle

@@ -365,7 +365,7 @@      in intoRope line  {- |-Pad a pieve of text on the left with a specified character to the desired+Pad a piece of text on the left with a specified character to the desired width. This function is named in homage to the famous result from Computer Science known as @leftPad@ which has a glorious place in the history of the world-wide web.