git.iko.soy/text
on builder help sign in
text/Data/Text/Foreign.hs
146 lines 5.0 kB history raw
1{-# LANGUAGE BangPatterns, CPP, GeneralizedNewtypeDeriving #-}
2-- |
3-- Module : Data.Text.Foreign
4-- Copyright : (c) 2009, 2010 Bryan O'Sullivan
5--
6-- License : BSD-style
7-- Maintainer : bos@serpentine.com, rtomharper@googlemail.com,
8-- duncan@haskell.org
9-- Stability : experimental
10-- Portability : GHC
11--
12-- Support for using 'Text' data with native code via the Haskell
13-- foreign function interface.
15module Data.Text.Foreign
16 (
17 -- * Interoperability with native code
18 -- $interop
19 I16
20 -- * Safe conversion functions
21 , fromPtr
22 , useAsPtr
23 , asForeignPtr
24 -- * Unsafe conversion code
25 , lengthWord16
26 , unsafeCopyToPtr
27 -- * Low-level manipulation
28 -- $lowlevel
29 , dropWord16
30 , takeWord16
31 ) where
33#if defined(ASSERTS)
34import Control.Exception (assert)
35#endif
36import Control.Monad.ST (unsafeIOToST)
37import Data.Text.Internal (Text(..), empty)
38import Data.Text.Unsafe (lengthWord16)
39import qualified Data.Text.Array as A
40import Data.Word (Word16)
41import Foreign.Marshal.Alloc (allocaBytes)
42import Foreign.Ptr (Ptr, castPtr, plusPtr)
43import Foreign.ForeignPtr (ForeignPtr, mallocForeignPtrArray, withForeignPtr)
44import Foreign.Storable (peek, poke)
46-- $interop
47--
48-- The 'Text' type is implemented using arrays that are not guaranteed
49-- to have a fixed address in the Haskell heap. All communication with
50-- native code must thus occur by copying data back and forth.
51--
52-- The 'Text' type's internal representation is UTF-16, using the
53-- platform's native endianness. This makes copied data suitable for
54-- use with native libraries that use a similar representation, such
55-- as ICU. To interoperate with native libraries that use different
56-- internal representations, such as UTF-8 or UTF-32, consider using
57-- the functions in the 'Data.Text.Encoding' module.
59-- | A type representing a number of UTF-16 code units.
60newtype I16 = I16 Int
61 deriving (Bounded, Enum, Eq, Integral, Num, Ord, Read, Real, Show)
63-- | /O(n)/ Create a new 'Text' from a 'Ptr' 'Word16' by copying the
64-- contents of the array.
65fromPtr :: Ptr Word16 -- ^ source array
66 -> I16 -- ^ length of source array (in 'Word16' units)
67 -> IO Text
68fromPtr _ (I16 0) = return empty
69fromPtr ptr (I16 len) =
70#if defined(ASSERTS)
71 assert (len > 0) $
72#endif
73 return $! Text arr 0 len
74 where
75 arr = A.run (A.new len >>= copy)
76 copy marr = loop ptr 0
77 where
78 loop !p !i | i == len = return marr
79 | otherwise = do
80 A.unsafeWrite marr i =<< unsafeIOToST (peek p)
81 loop (p `plusPtr` 2) (i + 1)
83-- $lowlevel
84--
85-- Foreign functions that use UTF-16 internally may return indices in
86-- units of 'Word16' instead of characters. These functions may
87-- safely be used with such indices, as they will adjust offsets if
88-- necessary to preserve the validity of a Unicode string.
90-- | /O(1)/ Return the prefix of the 'Text' of @n@ 'Word16' units in
91-- length.
92--
93-- If @n@ would cause the 'Text' to end inside a surrogate pair, the
94-- end of the prefix will be advanced by one additional 'Word16' unit
95-- to maintain its validity.
96takeWord16 :: I16 -> Text -> Text
97takeWord16 (I16 n) t@(Text arr off len)
98 | n <= 0 = empty
99 | n >= len || m >= len = t
100 | otherwise = Text arr off m
101 where
102 m | w < 0xDB00 || w > 0xD8FF = n
103 | otherwise = n+1
104 w = A.unsafeIndex arr (off+n-1)
106-- | /O(1)/ Return the suffix of the 'Text', with @n@ 'Word16' units
107-- dropped from its beginning.
108--
109-- If @n@ would cause the 'Text' to begin inside a surrogate pair, the
110-- beginning of the suffix will be advanced by one additional 'Word16'
111-- unit to maintain its validity.
112dropWord16 :: I16 -> Text -> Text
113dropWord16 (I16 n) t@(Text arr off len)
114 | n <= 0 = t
115 | n >= len || m >= len = empty
116 | otherwise = Text arr (off+m) (len-m)
117 where
118 m | w < 0xD800 || w > 0xDBFF = n
119 | otherwise = n+1
120 w = A.unsafeIndex arr (off+n-1)
122-- | /O(n)/ Copy a 'Text' to an array. The array is assumed to be big
123-- enough to hold the contents of the entire 'Text'.
124unsafeCopyToPtr :: Text -> Ptr Word16 -> IO ()
125unsafeCopyToPtr (Text arr off len) ptr = loop ptr off
126 where
127 end = off + len
128 loop !p !i | i == end = return ()
129 | otherwise = do
130 poke p (A.unsafeIndex arr i)
131 loop (p `plusPtr` 2) (i + 1)
133-- | /O(n)/ Perform an action on a temporary, mutable copy of a
134-- 'Text'. The copy is freed as soon as the action returns.
135useAsPtr :: Text -> (Ptr Word16 -> I16 -> IO a) -> IO a
136useAsPtr t@(Text _arr _off len) action =
137 allocaBytes (len * 2) $ \buf -> do
138 unsafeCopyToPtr t buf
139 action (castPtr buf) (fromIntegral len)
141-- | /O(n)/ Make a mutable copy of a 'Text'.
142asForeignPtr :: Text -> IO (ForeignPtr Word16, I16)
143asForeignPtr t@(Text _arr _off len) = do
144 fp <- mallocForeignPtrArray len
145 withForeignPtr fp $ unsafeCopyToPtr t
146 return (fp, I16 len)