<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <!--Rendered using the Haskell Html Library v0.2--> <HTML ><HEAD ><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" ><TITLE >Data.Text.Foreign</TITLE ><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css" ><SCRIPT SRC="haddock-util.js" TYPE="text/javascript" ></SCRIPT ><SCRIPT TYPE="text/javascript" >window.onload = function () {setSynopsis("mini_Data-Text-Foreign.html")};</SCRIPT ></HEAD ><BODY ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="topbar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" " ></TD ><TD CLASS="title" >text-0.8.1.0: An efficient packed Unicode text type.</TD ><TD CLASS="topbut" ><A HREF="src/Data-Text-Foreign.html" >Source code</A ></TD ><TD CLASS="topbut" ><A HREF="index.html" >Contents</A ></TD ><TD CLASS="topbut" ><A HREF="doc-index.html" >Index</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="modulebar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><FONT SIZE="6" >Data.Text.Foreign</FONT ></TD ><TD ALIGN="right" ><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="infohead" >Portability</TD ><TD CLASS="infoval" >GHC</TD ></TR ><TR ><TD CLASS="infohead" >Stability</TD ><TD CLASS="infoval" >experimental</TD ></TR ><TR ><TD CLASS="infohead" >Maintainer</TD ><TD CLASS="infoval" >bos@serpentine.com, rtomharper@googlemail.com, duncan@haskell.org</TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="section4" ><B >Contents</B ></TD ></TR ><TR ><TD ><DL ><DT ><A HREF="#1" >Interoperability with native code </A ></DT ><DT ><A HREF="#2" >Safe conversion functions </A ></DT ><DT ><A HREF="#3" >Unsafe conversion code </A ></DT ><DT ><A HREF="#4" >Low-level manipulation </A ></DT ></DL ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Description</TD ></TR ><TR ><TD CLASS="doc" >Support for using <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > data with native code via the Haskell foreign function interface. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Synopsis</TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="#v%3AfromPtr" >fromPtr</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > <A HREF="Data-Text.html#t%3AText" >Text</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AuseAsPtr" >useAsPtr</A > :: <A HREF="Data-Text.html#t%3AText" >Text</A > -> (<A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > a) -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > a</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AlengthWord16" >lengthWord16</A > :: <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AunsafeCopyToPtr" >unsafeCopyToPtr</A > :: <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > <A HREF="/usr/share/doc/ghc/html/libraries/ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AdropWord16" >dropWord16</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AtakeWord16" >takeWord16</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="1" ><A NAME="1" >Interoperability with native code </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >The <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > type is implemented using arrays that are not guaranteed to have a fixed address in the Haskell heap. All communication with native code must thus occur by copying data back and forth. </P ><P >The <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > type's internal representation is UTF-16, using the platform's native endianness. This makes copied data suitable for use with native libraries that use a similar representation, such as ICU. To interoperate with native libraries that use different internal representations, such as UTF-8 or UTF-32, consider using the functions in the Data.Text.Encoding module. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="2" ><A NAME="2" >Safe conversion functions </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:fromPtr" ><A NAME="v%3AfromPtr" ></A ></A ><B >fromPtr</B ></TD ><TD CLASS="declbut" ><A HREF="src/Data-Text-Foreign.html#fromPtr" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="arg" >:: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TD ><TD CLASS="rdoc" >source array </TD ></TR ><TR ><TD CLASS="arg" >-> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A ></TD ><TD CLASS="rdoc" >length of source array (in <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > units) </TD ></TR ><TR ><TD CLASS="arg" >-> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > <A HREF="Data-Text.html#t%3AText" >Text</A ></TD ><TD CLASS="rdoc" ></TD ></TR ><TR ><TD CLASS="ndoc" COLSPAN="2" ><EM >O(n)</EM > Create a new <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > from a <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A ></TT > <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > by copying the contents of the array. </TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:useAsPtr" ><A NAME="v%3AuseAsPtr" ></A ></A ><B >useAsPtr</B > :: <A HREF="Data-Text.html#t%3AText" >Text</A > -> (<A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > a) -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > a</TD ><TD CLASS="declbut" ><A HREF="src/Data-Text-Foreign.html#useAsPtr" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><EM >O(n)</EM > Perform an action on a temporary, mutable copy of a <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT >. The copy is freed as soon as the action returns. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="3" ><A NAME="3" >Unsafe conversion code </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:lengthWord16" ><A NAME="v%3AlengthWord16" ></A ></A ><B >lengthWord16</B > :: <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-Text-Unsafe.html#lengthWord16" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><EM >O(1)</EM > Return the length of a <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > in units of Word16. This is useful for sizing a target array appropriately before using unsafeCopyToPtr. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:unsafeCopyToPtr" ><A NAME="v%3AunsafeCopyToPtr" ></A ></A ><B >unsafeCopyToPtr</B > :: <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > <A HREF="/usr/share/doc/ghc/html/libraries/ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-Text-Foreign.html#unsafeCopyToPtr" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><EM >O(n)</EM > Copy a <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > to an array. The array is assumed to be big enough to hold the contents of the entire <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT >. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="4" ><A NAME="4" >Low-level manipulation </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" >Foreign functions that use UTF-16 internally may return indices in units of <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > instead of characters. These functions may safely be used with such indices, as they will adjust offsets if necessary to preserve the validity of a Unicode string. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:dropWord16" ><A NAME="v%3AdropWord16" ></A ></A ><B >dropWord16</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-Text-Foreign.html#dropWord16" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P ><EM >O(1)</EM > Return the suffix of the <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT >, with <TT >n</TT > <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > units dropped from its beginning. </P ><P >If <TT >n</TT > would cause the <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > to begin inside a surrogate pair, the beginning of the suffix will be advanced by one additional <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > unit to maintain its validity. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:takeWord16" ><A NAME="v%3AtakeWord16" ></A ></A ><B >takeWord16</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A > -> <A HREF="Data-Text.html#t%3AText" >Text</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-Text-Foreign.html#takeWord16" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P ><EM >O(1)</EM > Return the prefix of the <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > of <TT >n</TT > <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > units in length. </P ><P >If <TT >n</TT > would cause the <TT ><A HREF="Data-Text.html#t%3AText" >Text</A ></TT > to end inside a surrogate pair, the end of the prefix will be advanced by one additional <TT ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TT > unit to maintain its validity. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="botbar" >Produced by <A HREF="http://www.haskell.org/haddock/" >Haddock</A > version 2.6.1</TD ></TR ></TABLE ></BODY ></HTML >