@@ -183,6 +183,9 @@ module Data.Text
183183
184184 -- -* Ordered text
185185 -- , sort
186+
187+ -- * Low level operations
188+ , copy
186189 ) where
187190
188191import Prelude (Char, Bool(..), Int, Maybe(..), String,
@@ -1577,3 +1580,19 @@ emptyError fun = P.error $ "Data.Text." ++ fun ++ ": empty input"
15771580
15781581overflowError :: String -> a
15791582overflowError fun = P.error $ "Data.Text." ++ fun ++ ": size overflow"
1583+
1584+-- | /O(n)/ Make a distinct copy of the given string, sharing no
1585+-- storage with the original string.
1586+--
1587+-- As an example, suppose you read a large string, of which you need
1588+-- only a small portion. If you do not use 'copy', the entire original
1589+-- array will be kept alive in memory by the smaller string. Making a
1590+-- copy \"breaks the link\" to the original array, allowing it to be
1591+-- garbage collected if there are no other live references to it.
1592+copy :: Text -> Text
1593+copy (Text arr off len) = Text (A.run go) 0 len
1594+ where
1595+ go = do
1596+ marr <- A.new len
1597+ A.copyI marr 0 arr off len
1598+ return marr