<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>ICU 4.4: utext.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.1 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
<li><a href="globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>utext.h File Reference</h1>
<p>C API: Abstract Unicode Text API.
<a href="#_details">More...</a></p>
<code>#include "<a class="el" href="utypes_8h_source.html">unicode/utypes.h</a>"</code><br/>
<code>#include "<a class="el" href="uchar_8h_source.html">unicode/uchar.h</a>"</code><br/>
<p><a href="utext_8h_source.html">Go to the source code of this file.</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Data Structures</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structUTextFuncs.html">UTextFuncs</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">(public) Function dispatch table for <a class="el" href="structUText.html" title="UText struct.">UText</a>. <a href="structUTextFuncs.html#_details">More...</a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structUText.html">UText</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight"><a class="el" href="structUText.html" title="UText struct.">UText</a> struct. <a href="structUText.html#_details">More...</a><br/></td></tr>
<tr><td colspan="2"><h2>Defines</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#afedc50a892711dbf795af1fb8aac40cf">UTEXT_CURRENT32</a>(ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">inline version of <a class="el" href="utext_8h.html#a890bfd8f4c97a85bb70a22eabb34b716" title="Get the code point at the current iteration position, or U_SENTINEL (-1) if the iteration...">utext_current32()</a>, for performance-critical situations. <a href="#afedc50a892711dbf795af1fb8aac40cf"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#aa4b973aeeb5f10f8aec454545f85b6a2">UTEXT_NEXT32</a>(ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">inline version of <a class="el" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0" title="Get the code point at the current iteration position of the UText, and advance the...">utext_next32()</a>, for performance-critical situations. <a href="#aa4b973aeeb5f10f8aec454545f85b6a2"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a8aa3d9bae7b252622fe8e70e87758205">UTEXT_PREVIOUS32</a>(ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">inline version of <a class="el" href="utext_8h.html#af762d727316244730b78667d12e26dd6" title="Move the iterator position to the character (code point) whose index precedes the...">utext_previous32()</a>, for performance-critical situations. <a href="#a8aa3d9bae7b252622fe8e70e87758205"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a23a003b461019bea876827b8b24cb364">UTEXT_GETNATIVEINDEX</a>(ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">inline version of <a class="el" href="utext_8h.html#acd28c25814787d3d1620e3edb8f917fd" title="Get the current iterator position, which can range from 0 to the length of the text...">utext_getNativeIndex()</a>, for performance-critical situations. <a href="#a23a003b461019bea876827b8b24cb364"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a74aa6ff1add5886508657997ca8d4747">UTEXT_SETNATIVEINDEX</a>(ut, ix)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">inline version of <a class="el" href="utext_8h.html#a530b4bb7f0e577008e4930f2b39ecd8a" title="Set the current iteration position to the nearest code point boundary at or preceding...">utext_setNativeIndex()</a>, for performance-critical situations. <a href="#a74aa6ff1add5886508657997ca8d4747"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a3dc916f710c0d3f17fe2a220384bcc8c">UTEXT_INITIALIZER</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">initializer to be used with local (stack) instances of a <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. <a href="#a3dc916f710c0d3f17fe2a220384bcc8c"></a><br/></td></tr>
<tr><td colspan="2"><h2>Typedefs</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="structUText.html">UText</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a8da22111033cc0c063d89cae348ec1e4">UText</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">C typedef for struct <a class="el" href="structUText.html" title="UText struct.">UText</a>. <a href="#a8da22111033cc0c063d89cae348ec1e4"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef <a class="el" href="structUText.html">UText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#ae29be5a512f69c3a9d871890225d07ec">UTextClone</a> (<a class="el" href="structUText.html">UText</a> *dest, const <a class="el" href="structUText.html">UText</a> *src, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> deep, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.clone(). <a href="#ae29be5a512f69c3a9d871890225d07ec"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a36bad470545b3183fff611c91312cc10">UTextNativeLength</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.nativeLength(). <a href="#a36bad470545b3183fff611c91312cc10"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a829af7190e7cee22c647af949ebb4730">UTextAccess</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> forward)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.access(). <a href="#a829af7190e7cee22c647af949ebb4730"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a62d7c17254aee81ba7ccf7acdf79f2dd">UTextExtract</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *dest, int32_t destCapacity, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.extract(). <a href="#a62d7c17254aee81ba7ccf7acdf79f2dd"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a0a84b5d0d434b0f1f71f77841cac3d97">UTextReplace</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, const <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *replacementText, int32_t replacmentLength, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.replace(). <a href="#a0a84b5d0d434b0f1f71f77841cac3d97"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef void </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#ad017072290f396d7bce8fb0712a232e8">UTextCopy</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, int64_t nativeDest, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> move, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.copy(). <a href="#ad017072290f396d7bce8fb0712a232e8"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#aa78b6ae4b98958554b7ee15de57e9c30">UTextMapOffsetToNative</a> (const <a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.mapOffsetToNative(). <a href="#aa78b6ae4b98958554b7ee15de57e9c30"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#ab14d770b0feb53e5c4677f998e6b5ad0">UTextMapNativeIndexToUTF16</a> (const <a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.mapIndexToUTF16(). <a href="#ab14d770b0feb53e5c4677f998e6b5ad0"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef void </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a689fd4dcd7e392532f979af8b33273b5">UTextClose</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function type declaration for UText.utextClose(). <a href="#a689fd4dcd7e392532f979af8b33273b5"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="structUTextFuncs.html">UTextFuncs</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#acaf57d3fd11db28583a36df05ec02295">UTextFuncs</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Function dispatch table for <a class="el" href="structUText.html" title="UText struct.">UText</a>. <a href="#acaf57d3fd11db28583a36df05ec02295"></a><br/></td></tr>
<tr><td colspan="2"><h2>Enumerations</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">enum </td><td class="memItemRight" valign="bottom">{ <br/>
<a class="el" href="utext_8h.html#a05589fbab0657f08285ebdfe93f5ec9ea752c07f9df260b5b0e234e15eab97f9f">UTEXT_PROVIDER_LENGTH_IS_EXPENSIVE</a> = 1,
<a class="el" href="utext_8h.html#a05589fbab0657f08285ebdfe93f5ec9ea52bb5c9cacd1f46eb87a856c71c073be">UTEXT_PROVIDER_STABLE_CHUNKS</a> = 2,
<a class="el" href="utext_8h.html#a05589fbab0657f08285ebdfe93f5ec9eac67ce6ecf6bf959645e282f7194fbe3b">UTEXT_PROVIDER_WRITABLE</a> = 3,
<a class="el" href="utext_8h.html#a05589fbab0657f08285ebdfe93f5ec9ea40c5cd24aea472f3752b4833b9ce63ca">UTEXT_PROVIDER_HAS_META_DATA</a> = 4,
<br/>
<a class="el" href="utext_8h.html#a05589fbab0657f08285ebdfe93f5ec9ea75695072a896ec104b5d77598a7429f7">UTEXT_PROVIDER_OWNS_TEXT</a> = 5
<br/>
}</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight"><p><a class="el" href="structUText.html" title="UText struct.">UText</a> provider properties (bit field indexes). </p>
<a href="utext_8h.html#a05589fbab0657f08285ebdfe93f5ec9e">More...</a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">enum </td><td class="memItemRight" valign="bottom">{ <b>UTEXT_MAGIC</b> = 0x345ad82c
}</td></tr>
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structUText.html">UText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a303eb28b0f98498dfcb063e05ab2695c">utext_close</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Close function for <a class="el" href="structUText.html" title="UText struct.">UText</a> instances. <a href="#a303eb28b0f98498dfcb063e05ab2695c"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structUText.html">UText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a32e9e14644d140c3501a7a09e7ad5864">utext_openUTF8</a> (<a class="el" href="structUText.html">UText</a> *ut, const char *s, int64_t length, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Open a read-only <a class="el" href="structUText.html" title="UText struct.">UText</a> implementation for UTF-8 strings. <a href="#a32e9e14644d140c3501a7a09e7ad5864"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structUText.html">UText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#adf311525bdd2a7f155bbe5cbb4c4de15">utext_openUChars</a> (<a class="el" href="structUText.html">UText</a> *ut, const <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *s, int64_t length, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Open a read-only <a class="el" href="structUText.html" title="UText struct.">UText</a> for UChar * string. <a href="#adf311525bdd2a7f155bbe5cbb4c4de15"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structUText.html">UText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a8732a0c34ee4764c08f70b7a8d7ca4d4">utext_clone</a> (<a class="el" href="structUText.html">UText</a> *dest, const <a class="el" href="structUText.html">UText</a> *src, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> deep, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> readOnly, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Clone a <a class="el" href="structUText.html" title="UText struct.">UText</a>. <a href="#a8732a0c34ee4764c08f70b7a8d7ca4d4"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a592a289ae040b2e610e9aaa9032ce276">utext_equals</a> (const <a class="el" href="structUText.html">UText</a> *a, const <a class="el" href="structUText.html">UText</a> *b)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Compare two <a class="el" href="structUText.html" title="UText struct.">UText</a> objects for equality. <a href="#a592a289ae040b2e610e9aaa9032ce276"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#ab6a809d8168c1ccf30746cd57234a59e">utext_nativeLength</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the length of the text. <a href="#ab6a809d8168c1ccf30746cd57234a59e"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a18dd4010f0d9fbe9c920f3ce954990ed">utext_isLengthExpensive</a> (const <a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return TRUE if calculating the length of the text could be expensive. <a href="#a18dd4010f0d9fbe9c920f3ce954990ed"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#aab911e6df41b5e5a90fd09d2f0aa4fbc">utext_char32At</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns the code point at the requested index, or U_SENTINEL (-1) if it is out of bounds. <a href="#aab911e6df41b5e5a90fd09d2f0aa4fbc"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a890bfd8f4c97a85bb70a22eabb34b716">utext_current32</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the code point at the current iteration position, or U_SENTINEL (-1) if the iteration has reached the end of the input text. <a href="#a890bfd8f4c97a85bb70a22eabb34b716"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0">utext_next32</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the code point at the current iteration position of the <a class="el" href="structUText.html" title="UText struct.">UText</a>, and advance the position to the first index following the character. <a href="#ad4c8e3ba851a3482b2c77cc58cff9ad0"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#af762d727316244730b78667d12e26dd6">utext_previous32</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Move the iterator position to the character (code point) whose index precedes the current position, and return that character. <a href="#af762d727316244730b78667d12e26dd6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a819b23625de643f71280c076feac31a7">utext_next32From</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Set the iteration index and return the code point at that index. <a href="#a819b23625de643f71280c076feac31a7"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a7d12867d3baae5beeb34351e172b5cd8">utext_previous32From</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Set the iteration index, and return the code point preceding the one specified by the initial index. <a href="#a7d12867d3baae5beeb34351e172b5cd8"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#acd28c25814787d3d1620e3edb8f917fd">utext_getNativeIndex</a> (const <a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the current iterator position, which can range from 0 to the length of the text. <a href="#acd28c25814787d3d1620e3edb8f917fd"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a530b4bb7f0e577008e4930f2b39ecd8a">utext_setNativeIndex</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Set the current iteration position to the nearest code point boundary at or preceding the specified index. <a href="#a530b4bb7f0e577008e4930f2b39ecd8a"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#af91afb68d5059ec704d8d6969288c00d">utext_moveIndex32</a> (<a class="el" href="structUText.html">UText</a> *ut, int32_t delta)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Move the iterator postion by delta code points. <a href="#af91afb68d5059ec704d8d6969288c00d"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a2c703c15aa63fc6555d50feec4f6b3c6">utext_getPreviousNativeIndex</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the native index of the character preceeding the current position. <a href="#a2c703c15aa63fc6555d50feec4f6b3c6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#aec0833241ef75e474f3dbf4dcf3be9c3">utext_extract</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *dest, int32_t destCapacity, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Extract text from a <a class="el" href="structUText.html" title="UText struct.">UText</a> into a UChar buffer. <a href="#aec0833241ef75e474f3dbf4dcf3be9c3"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a5143c3dc59cf1614a50a5873fd49171f">utext_compare</a> (<a class="el" href="structUText.html">UText</a> *s1, int32_t length1, <a class="el" href="structUText.html">UText</a> *s2, int32_t length2)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Compare two UTexts (binary order). <a href="#a5143c3dc59cf1614a50a5873fd49171f"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#adeaed071bf866b2af77cc5708c98e589">utext_compareNativeLimit</a> (<a class="el" href="structUText.html">UText</a> *s1, int64_t limit1, <a class="el" href="structUText.html">UText</a> *s2, int64_t limit2)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Compare two UTexts (binary order). <a href="#adeaed071bf866b2af77cc5708c98e589"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a3f1953865cbbd5c2846166e802701a08">utext_caseCompare</a> (<a class="el" href="structUText.html">UText</a> *s1, int32_t length1, <a class="el" href="structUText.html">UText</a> *s2, int32_t length2, uint32_t options, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *pErrorCode)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Compare two UTexts case-insensitively using full case folding. <a href="#a3f1953865cbbd5c2846166e802701a08"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a0bf112f899232a46c0c02333d44b2289">utext_caseCompareNativeLimit</a> (<a class="el" href="structUText.html">UText</a> *s1, int64_t limit1, <a class="el" href="structUText.html">UText</a> *s2, int64_t limit2, uint32_t options, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *pErrorCode)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Compare two UTexts case-insensitively using full case folding. <a href="#a0bf112f899232a46c0c02333d44b2289"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#af67295033b5dc1b2951b8b05e5ce9222">utext_isWritable</a> (const <a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return TRUE if the text can be written (modified) with <a class="el" href="utext_8h.html#aa781cea4987dda8a7c5f0351e311bf07" title="Replace a range of the original text with a replacement text.">utext_replace()</a> or <a class="el" href="utext_8h.html#abe74b66b8da9b9de17ea7e59af395c53" title="Copy or move a substring from one position to another within the text, while retaining...">utext_copy()</a>. <a href="#af67295033b5dc1b2951b8b05e5ce9222"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a5ca583f3d6592f6e4d00bd43a9bb4952">utext_hasMetaData</a> (const <a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Test whether there is meta data associated with the text. <a href="#a5ca583f3d6592f6e4d00bd43a9bb4952"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#aa781cea4987dda8a7c5f0351e311bf07">utext_replace</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, const <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *replacementText, int32_t replacementLength, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Replace a range of the original text with a replacement text. <a href="#aa781cea4987dda8a7c5f0351e311bf07"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#abe74b66b8da9b9de17ea7e59af395c53">utext_copy</a> (<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, int64_t destIndex, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> move, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Copy or move a substring from one position to another within the text, while retaining any metadata associated with the text. <a href="#abe74b66b8da9b9de17ea7e59af395c53"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a1ea9abacabf9f48914104dba66d932ff">utext_freeze</a> (<a class="el" href="structUText.html">UText</a> *ut)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structUText.html">UText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="utext_8h.html#a024e9470afd51e1ae247dcbfbbbe8a67">utext_setup</a> (<a class="el" href="structUText.html">UText</a> *ut, int32_t extraSpace, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Common function for use by Text Provider implementations to allocate and/or initialize a new <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. <a href="#a024e9470afd51e1ae247dcbfbbbe8a67"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>C API: Abstract Unicode Text API. </p>
<p>The Text Access API provides a means to allow text that is stored in alternative formats to work with ICU services. ICU normally operates on text that is stored in UTF-16 format, in (UChar *) arrays for the C APIs or as type <a class="el" href="classUnicodeString.html" title="UnicodeString is a string class that stores Unicode characters directly and provides...">UnicodeString</a> for C++ APIs.</p>
<p>ICU Text Access allows other formats, such as UTF-8 or non-contiguous UTF-16 strings, to be placed in a <a class="el" href="structUText.html" title="UText struct.">UText</a> wrapper and then passed to ICU services.</p>
<p>There are three general classes of usage for <a class="el" href="structUText.html" title="UText struct.">UText</a>:</p>
<p>Application Level Use. This is the simplest usage - applications would use one of the utext_open() functions on their input text, and pass the resulting <a class="el" href="structUText.html" title="UText struct.">UText</a> to the desired ICU service.</p>
<p>Second is usage in ICU Services, such as break iteration, that will need to operate on input presented to them as a <a class="el" href="structUText.html" title="UText struct.">UText</a>. These implementations will need to use the iteration and related <a class="el" href="structUText.html" title="UText struct.">UText</a> functions to gain access to the actual text.</p>
<p>The third class of <a class="el" href="structUText.html" title="UText struct.">UText</a> users are "text providers." These are the <a class="el" href="structUText.html" title="UText struct.">UText</a> implementations for the various text storage formats. An application or system with a unique text storage format can implement a set of <a class="el" href="structUText.html" title="UText struct.">UText</a> provider functions for that format, which will then allow ICU services to operate on that format.</p>
<p><em>Iterating over text</em></p>
<p>Here is sample code for a forward iteration over the contents of a <a class="el" href="structUText.html" title="UText struct.">UText</a></p>
<div class="fragment"><pre class="fragment"> <a class="code" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809" title="Define UChar32 as a type for single Unicode code points.">UChar32</a> c;
<a class="code" href="structUText.html" title="UText struct.">UText</a> *ut = whatever();
<span class="keywordflow">for</span> (c=<a class="code" href="utext_8h.html#a819b23625de643f71280c076feac31a7" title="Set the iteration index and return the code point at that index.">utext_next32From</a>(ut, 0); c>=0; c=<a class="code" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0" title="Get the code point at the current iteration position of the UText, and advance the...">utext_next32</a>(ut)) {
<span class="comment">// do whatever with the codepoint c here.</span>
}
</pre></div><p>And here is similar code to iterate in the reverse direction, from the end of the text towards the beginning.</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809" title="Define UChar32 as a type for single Unicode code points.">UChar32</a> c;
<a class="code" href="structUText.html" title="UText struct.">UText</a> *ut = whatever();
<span class="keywordtype">int</span> textLength = <a class="code" href="utext_8h.html#ab6a809d8168c1ccf30746cd57234a59e" title="Get the length of the text.">utext_nativeLength</a>(ut);
<span class="keywordflow">for</span> (c=<a class="code" href="utext_8h.html#a7d12867d3baae5beeb34351e172b5cd8" title="Set the iteration index, and return the code point preceding the one specified by...">utext_previous32From</a>(ut, textLength); c>=0; c=<a class="code" href="utext_8h.html#af762d727316244730b78667d12e26dd6" title="Move the iterator position to the character (code point) whose index precedes the...">utext_previous32</a>(ut)) {
<span class="comment">// do whatever with the codepoint c here.</span>
}
</pre></div><p><em>Characters and Indexing</em></p>
<p>Indexing into text by <a class="el" href="structUText.html" title="UText struct.">UText</a> functions is nearly always in terms of the native indexing of the underlying text storage. The storage format could be UTF-8 or UTF-32, for example. When coding to the <a class="el" href="structUText.html" title="UText struct.">UText</a> access API, no assumptions can be made regarding the size of characters, or how far an index may move when iterating between characters.</p>
<p>All indices supplied to <a class="el" href="structUText.html" title="UText struct.">UText</a> functions are pinned to the length of the text. An out-of-bounds index is not considered to be an error, but is adjusted to be in the range 0 <= index <= length of input text.</p>
<p>When an index position is returned from a <a class="el" href="structUText.html" title="UText struct.">UText</a> function, it will be a native index to the underlying text. In the case of multi-unit characters, it will always refer to the first position of the character, never to the interior. This is essentially the same thing as saying that a returned index will always point to a boundary between characters.</p>
<p>When a native index is supplied to a <a class="el" href="structUText.html" title="UText struct.">UText</a> function, all indices that refer to any part of a multi-unit character representation are considered to be equivalent. In the case of multi-unit characters, an incoming index will be logically normalized to refer to the start of the character.</p>
<p>It is possible to test whether a native index is on a code point boundary by doing a <a class="el" href="utext_8h.html#a530b4bb7f0e577008e4930f2b39ecd8a" title="Set the current iteration position to the nearest code point boundary at or preceding...">utext_setNativeIndex()</a> followed by a <a class="el" href="utext_8h.html#acd28c25814787d3d1620e3edb8f917fd" title="Get the current iterator position, which can range from 0 to the length of the text...">utext_getNativeIndex()</a>. If the index is returned unchanged, it was on a code point boundary. If an adjusted index is returned, the original index referred to the interior of a character.</p>
<p><em>Conventions for calling <a class="el" href="structUText.html" title="UText struct.">UText</a> functions</em></p>
<p>Most <a class="el" href="structUText.html" title="UText struct.">UText</a> access functions have as their first parameter a (<a class="el" href="structUText.html" title="UText struct.">UText</a> *) pointer, which specifies the <a class="el" href="structUText.html" title="UText struct.">UText</a> to be used. Unless otherwise noted, the pointer must refer to a valid, open <a class="el" href="structUText.html" title="UText struct.">UText</a>. Attempting to use a closed <a class="el" href="structUText.html" title="UText struct.">UText</a> or passing a NULL pointer is a programming error and will produce undefined results or NULL pointer exceptions.</p>
<p>The UText_Open family of functions can either open an existing (closed) <a class="el" href="structUText.html" title="UText struct.">UText</a>, or heap allocate a new <a class="el" href="structUText.html" title="UText struct.">UText</a>. Here is sample code for creating a stack-allocated <a class="el" href="structUText.html" title="UText struct.">UText</a>.</p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">char</span> *s = whatever(); <span class="comment">// A utf-8 string </span>
U_ErrorCode status = <a class="code" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78caa43dbfc9499c5f911d04e1a0ca3bf6f9" title="No error, no warning.">U_ZERO_ERROR</a>;
<a class="code" href="structUText.html" title="UText struct.">UText</a> ut = <a class="code" href="utext_8h.html#a3dc916f710c0d3f17fe2a220384bcc8c" title="initializer to be used with local (stack) instances of a UText struct.">UTEXT_INITIALIZER</a>;
<a class="code" href="utext_8h.html#a32e9e14644d140c3501a7a09e7ad5864" title="Open a read-only UText implementation for UTF-8 strings.">utext_openUTF8</a>(ut, s, -1, &status);
<span class="keywordflow">if</span> (<a class="code" href="utypes_8h.html#a4d202200b6aa6f3c965ea370e0c8155f" title="Does the error code indicate a failure?">U_FAILURE</a>(status)) {
<span class="comment">// error handling</span>
} <span class="keywordflow">else</span> {
<span class="comment">// work with the UText</span>
}
</pre></div><p>Any existing <a class="el" href="structUText.html" title="UText struct.">UText</a> passed to an open function _must_ have been initialized, either by the UTEXT_INITIALIZER, or by having been originally heap-allocated by an open function. Passing NULL will cause the open function to heap-allocate and fully initialize a new <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<p>Definition in file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
<hr/><h2>Define Documentation</h2>
<a class="anchor" id="afedc50a892711dbf795af1fb8aac40cf"></a><!-- doxytag: member="utext.h::UTEXT_CURRENT32" ref="afedc50a892711dbf795af1fb8aac40cf" args="(ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define UTEXT_CURRENT32</td>
<td>(</td>
<td class="paramtype">ut </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<b>Value:</b><div class="fragment"><pre class="fragment">((ut)->chunkOffset < (ut)->chunkLength && ((ut)->chunkContents)[(ut)->chunkOffset]<0xd800 ? \
((ut)->chunkContents)[((ut)->chunkOffset)] : <a class="code" href="utext_8h.html#a890bfd8f4c97a85bb70a22eabb34b716" title="Get the code point at the current iteration position, or U_SENTINEL (-1) if the iteration...">utext_current32</a>(ut))
</pre></div>
<p>inline version of <a class="el" href="utext_8h.html#a890bfd8f4c97a85bb70a22eabb34b716" title="Get the code point at the current iteration position, or U_SENTINEL (-1) if the iteration...">utext_current32()</a>, for performance-critical situations. </p>
<p>Get the code point at the current iteration position of the <a class="el" href="structUText.html" title="UText struct.">UText</a>. Returns U_SENTINEL (-1) if the position is at the end of the text.</p>
<dl class="internal"><dt><b><a class="el" href="internal.html#_internal000109">Internal:</a></b></dt><dd>Do not use. This API is for internal use only. ICU 4.4 technology preview </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l00844">844</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a23a003b461019bea876827b8b24cb364"></a><!-- doxytag: member="utext.h::UTEXT_GETNATIVEINDEX" ref="a23a003b461019bea876827b8b24cb364" args="(ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define UTEXT_GETNATIVEINDEX</td>
<td>(</td>
<td class="paramtype">ut </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<b>Value:</b><div class="fragment"><pre class="fragment">((ut)->chunkOffset <= (ut)->nativeIndexingLimit? \
(ut)->chunkNativeStart+(ut)->chunkOffset : \
(ut)->pFuncs->mapOffsetToNative(ut))
</pre></div>
<p>inline version of <a class="el" href="utext_8h.html#acd28c25814787d3d1620e3edb8f917fd" title="Get the current iterator position, which can range from 0 to the length of the text...">utext_getNativeIndex()</a>, for performance-critical situations. </p>
<p>Get the current iterator position, which can range from 0 to the length of the text. The position is a native index into the input text, in whatever format it may have (possibly UTF-8 for example), and may not always be the same as the corresponding UChar (UTF-16) index. The returned position will always be aligned to a code point boundary.</p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001960">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l00890">890</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a3dc916f710c0d3f17fe2a220384bcc8c"></a><!-- doxytag: member="utext.h::UTEXT_INITIALIZER" ref="a3dc916f710c0d3f17fe2a220384bcc8c" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define UTEXT_INITIALIZER</td>
</tr>
</table>
</div>
<div class="memdoc">
<b>Value:</b><div class="fragment"><pre class="fragment">{ \
UTEXT_MAGIC, <span class="comment">/* magic */</span> \
0, <span class="comment">/* flags */</span> \
0, <span class="comment">/* providerProps */</span> \
<span class="keyword">sizeof</span>(<a class="code" href="structUText.html" title="UText struct.">UText</a>), <span class="comment">/* sizeOfStruct */</span> \
0, <span class="comment">/* chunkNativeLimit */</span> \
0, <span class="comment">/* extraSize */</span> \
0, <span class="comment">/* nativeIndexingLimit */</span> \
0, <span class="comment">/* chunkNativeStart */</span> \
0, <span class="comment">/* chunkOffset */</span> \
0, <span class="comment">/* chunkLength */</span> \
<a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <span class="comment">/* chunkContents */</span> \
<a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <span class="comment">/* pFuncs */</span> \
<a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <span class="comment">/* pExtra */</span> \
<a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <span class="comment">/* context */</span> \
<a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <span class="comment">/* p, q, r */</span> \
<a class="code" href="utypes_8h.html#a070d2ce7b6bb7e5c05602aa8c308d0c4" title="Define NULL if necessary, to 0 for C++ and to ((void *)0) for C.">NULL</a>, <span class="comment">/* privP */</span> \
0, 0, 0, <span class="comment">/* a, b, c */</span> \
0, 0, 0 <span class="comment">/* privA,B,C, */</span> \
}
</pre></div>
<p>initializer to be used with local (stack) instances of a <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. </p>
<p><a class="el" href="structUText.html" title="UText struct.">UText</a> structs must be initialized before passing them to one of the utext_open functions.</p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001980">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01711">1711</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="aa4b973aeeb5f10f8aec454545f85b6a2"></a><!-- doxytag: member="utext.h::UTEXT_NEXT32" ref="aa4b973aeeb5f10f8aec454545f85b6a2" args="(ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define UTEXT_NEXT32</td>
<td>(</td>
<td class="paramtype">ut </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<b>Value:</b><div class="fragment"><pre class="fragment">((ut)->chunkOffset < (ut)->chunkLength && ((ut)->chunkContents)[(ut)->chunkOffset]<0xd800 ? \
((ut)->chunkContents)[((ut)->chunkOffset)++] : <a class="code" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0" title="Get the code point at the current iteration position of the UText, and advance the...">utext_next32</a>(ut))
</pre></div>
<p>inline version of <a class="el" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0" title="Get the code point at the current iteration position of the UText, and advance the...">utext_next32()</a>, for performance-critical situations. </p>
<p>Get the code point at the current iteration position of the <a class="el" href="structUText.html" title="UText struct.">UText</a>, and advance the position to the first index following the character. This is a post-increment operation. Returns U_SENTINEL (-1) if the position is at the end of the text.</p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001958">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l00859">859</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a8aa3d9bae7b252622fe8e70e87758205"></a><!-- doxytag: member="utext.h::UTEXT_PREVIOUS32" ref="a8aa3d9bae7b252622fe8e70e87758205" args="(ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define UTEXT_PREVIOUS32</td>
<td>(</td>
<td class="paramtype">ut </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<b>Value:</b><div class="fragment"><pre class="fragment">((ut)->chunkOffset > 0 && \
(ut)->chunkContents[(ut)->chunkOffset-1] < 0xd800 ? \
(ut)->chunkContents[--((ut)->chunkOffset)] : <a class="code" href="utext_8h.html#af762d727316244730b78667d12e26dd6" title="Move the iterator position to the character (code point) whose index precedes the...">utext_previous32</a>(ut))
</pre></div>
<p>inline version of <a class="el" href="utext_8h.html#af762d727316244730b78667d12e26dd6" title="Move the iterator position to the character (code point) whose index precedes the...">utext_previous32()</a>, for performance-critical situations. </p>
<p>Move the iterator position to the character (code point) whose index precedes the current position, and return that character. This is a pre-decrement operation. Returns U_SENTINEL (-1) if the position is at the start of the text.</p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001959">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l00873">873</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a74aa6ff1add5886508657997ca8d4747"></a><!-- doxytag: member="utext.h::UTEXT_SETNATIVEINDEX" ref="a74aa6ff1add5886508657997ca8d4747" args="(ut, ix)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define UTEXT_SETNATIVEINDEX</td>
<td>(</td>
<td class="paramtype">ut, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">ix </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<b>Value:</b><div class="fragment"><pre class="fragment">{ int64_t __offset = (ix) - (ut)->chunkNativeStart; \
<span class="keywordflow">if</span> (__offset>=0 && __offset<=(int64_t)(ut)->nativeIndexingLimit) { \
(ut)->chunkOffset=(int32_t)__offset; \
} <span class="keywordflow">else</span> { \
<a class="code" href="utext_8h.html#a530b4bb7f0e577008e4930f2b39ecd8a" title="Set the current iteration position to the nearest code point boundary at or preceding...">utext_setNativeIndex</a>((ut), (ix)); } }
</pre></div>
<p>inline version of <a class="el" href="utext_8h.html#a530b4bb7f0e577008e4930f2b39ecd8a" title="Set the current iteration position to the nearest code point boundary at or preceding...">utext_setNativeIndex()</a>, for performance-critical situations. </p>
<p>Set the current iteration position to the nearest code point boundary at or preceding the specified index. The index is in the native units of the original input text. If the index is out of range, it will be pinned to be within the range of the input text.</p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001961">Stable:</a></b></dt><dd>ICU 3.8 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l00906">906</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<hr/><h2>Typedef Documentation</h2>
<a class="anchor" id="a8da22111033cc0c063d89cae348ec1e4"></a><!-- doxytag: member="utext.h::UText" ref="a8da22111033cc0c063d89cae348ec1e4" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="structUText.html">UText</a> <a class="el" href="structUText.html">UText</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>C typedef for struct <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001939">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l00151">151</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a829af7190e7cee22c647af949ebb4730"></a><!-- doxytag: member="utext.h::UTextAccess" ref="a829af7190e7cee22c647af949ebb4730" args="(UText *ut, int64_t nativeIndex, UBool forward)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> <a class="el" href="utext_8h.html#a829af7190e7cee22c647af949ebb4730">UTextAccess</a>(<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> forward)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.access(). </p>
<p>Get the description of the text chunk containing the text at a requested native index. The UText's iteration position will be left at the requested index. If the index is out of bounds, the iteration position will be left at the start or end of the string, as appropriate.</p>
<p>Chunks must begin and end on code point boundaries. A single code point comprised of multiple storage units must never span a chunk boundary.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> being accessed. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeIndex</em> </td><td>Requested index of the text to be accessed. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>forward</em> </td><td>If TRUE, then the returned chunk must contain text starting from the index, so that start<=index<limit. If FALSE, then the returned chunk must contain text before the index, so that start<index<=limit. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>True if the requested index could be accessed. The chunk will contain the requested text. False value if a chunk cannot be accessed (the requested index is out of bounds).</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="structUText.html" title="UText struct.">UText</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001970">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01178">1178</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="ae29be5a512f69c3a9d871890225d07ec"></a><!-- doxytag: member="utext.h::UTextClone" ref="ae29be5a512f69c3a9d871890225d07ec" args="(UText *dest, const UText *src, UBool deep, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef <a class="el" href="structUText.html">UText</a>* <a class="el" href="utext_8h.html#ae29be5a512f69c3a9d871890225d07ec">UTextClone</a>(<a class="el" href="structUText.html">UText</a> *dest, const <a class="el" href="structUText.html">UText</a> *src, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> deep, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.clone(). </p>
<p>clone a <a class="el" href="structUText.html" title="UText struct.">UText</a>. Much like opening a <a class="el" href="structUText.html" title="UText struct.">UText</a> where the source text is itself another <a class="el" href="structUText.html" title="UText struct.">UText</a>.</p>
<p>A deep clone will copy both the <a class="el" href="structUText.html" title="UText struct.">UText</a> data structures and the underlying text. The original and cloned <a class="el" href="structUText.html" title="UText struct.">UText</a> will operate completely independently; modifications made to the text in one will not effect the other. Text providers are not required to support deep clones. The user of clone() must check the status return and be prepared to handle failures.</p>
<p>A shallow clone replicates only the <a class="el" href="structUText.html" title="UText struct.">UText</a> data structures; it does not make a copy of the underlying text. Shallow clones can be used as an efficient way to have multiple iterators active in a single text string that is not being modified.</p>
<p>A shallow clone operation must not fail except for truly exceptional conditions such as memory allocation failures.</p>
<p>A <a class="el" href="structUText.html" title="UText struct.">UText</a> and its clone may be safely concurrently accessed by separate threads. This is true for both shallow and deep clones. It is the responsibility of the Text Provider to ensure that this thread safety constraint is met.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>A <a class="el" href="structUText.html" title="UText struct.">UText</a> struct to be filled in with the result of the clone operation, or NULL if the clone function should heap-allocate a new <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>src</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> to be cloned. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>deep</em> </td><td>TRUE to request a deep clone, FALSE for a shallow clone. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR should be returned if the text provider is unable to clone the original text. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The newly created clone, or NULL if the clone operation failed.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001968">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01138">1138</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a689fd4dcd7e392532f979af8b33273b5"></a><!-- doxytag: member="utext.h::UTextClose" ref="a689fd4dcd7e392532f979af8b33273b5" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef void <a class="el" href="utext_8h.html#a689fd4dcd7e392532f979af8b33273b5">UTextClose</a>(<a class="el" href="structUText.html">UText</a> *ut)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.utextClose(). </p>
<p>A Text Provider close function is only required for provider types that make allocations in their open function (or other functions) that must be cleaned when the <a class="el" href="structUText.html" title="UText struct.">UText</a> is closed.</p>
<p>The allocation of the <a class="el" href="structUText.html" title="UText struct.">UText</a> struct itself and any "extra" storage associated with the <a class="el" href="structUText.html" title="UText struct.">UText</a> is handled by the common <a class="el" href="structUText.html" title="UText struct.">UText</a> implementation and does not require provider specific cleanup in a close function.</p>
<p>Most <a class="el" href="structUText.html" title="UText struct.">UText</a> provider implementations do not need to implement this function.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>A <a class="el" href="structUText.html" title="UText struct.">UText</a> object to be closed.</td></tr>
</table>
</dd>
</dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001976">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01336">1336</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="ad017072290f396d7bce8fb0712a232e8"></a><!-- doxytag: member="utext.h::UTextCopy" ref="ad017072290f396d7bce8fb0712a232e8" args="(UText *ut, int64_t nativeStart, int64_t nativeLimit, int64_t nativeDest, UBool move, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef void <a class="el" href="utext_8h.html#ad017072290f396d7bce8fb0712a232e8">UTextCopy</a>(<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, int64_t nativeDest, <a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> move, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.copy(). </p>
<p>Copy or move a substring from one position to another within the text, while retaining any metadata associated with the text. This function is used to duplicate or reorder substrings. The destination index must not overlap the source range.</p>
<p>The text to be copied or moved is inserted at destIndex; it does not replace or overwrite any existing text.</p>
<p>This function need only be implemented for <a class="el" href="structUText.html" title="UText struct.">UText</a> types that support writing.</p>
<p>When using this function, there should be only a single <a class="el" href="structUText.html" title="UText struct.">UText</a> opened onto the underlying native text string. The function is responsible for updating the text chunk within the <a class="el" href="structUText.html" title="UText struct.">UText</a> to reflect the updated iteration position, taking into account any changes to the underlying string's structure caused by the replace operation.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> representing the text to be operated on. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeStart</em> </td><td>The index of the start of the region to be copied or moved </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeLimit</em> </td><td>The index of the character following the region to be replaced. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeDest</em> </td><td>The destination index to which the source substring is copied or moved. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>move</em> </td><td>If TRUE, then the substring is moved, not copied/duplicated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>receives any error status. Possible errors include U_NO_WRITE_PERMISSION</td></tr>
</table>
</dd>
</dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001973">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01277">1277</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a62d7c17254aee81ba7ccf7acdf79f2dd"></a><!-- doxytag: member="utext.h::UTextExtract" ref="a62d7c17254aee81ba7ccf7acdf79f2dd" args="(UText *ut, int64_t nativeStart, int64_t nativeLimit, UChar *dest, int32_t destCapacity, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int32_t <a class="el" href="utext_8h.html#a62d7c17254aee81ba7ccf7acdf79f2dd">UTextExtract</a>(<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *dest, int32_t destCapacity, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.extract(). </p>
<p>Extract text from a <a class="el" href="structUText.html" title="UText struct.">UText</a> into a UChar buffer. The range of text to be extracted is specified in the native indices of the <a class="el" href="structUText.html" title="UText struct.">UText</a> provider. These may not necessarily be UTF-16 indices. </p>
<p>The size (number of 16 bit UChars) in the data to be extracted is returned. The full amount is returned, even when the specified buffer size is smaller. </p>
<p>The extracted string will (if you are a user) / must (if you are a text provider) be NUL-terminated if there is sufficient space in the destination buffer.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> from which to extract data. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeStart</em> </td><td>the native index of the first characer to extract. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeLimit</em> </td><td>the native string index of the position following the last character to extract. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>the UChar (UTF-16) buffer into which the extracted text is placed </td></tr>
<tr><td valign="top"></td><td valign="top"><em>destCapacity</em> </td><td>The size, in UChars, of the destination buffer. May be zero for precomputing the required size. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>receives any error status. If U_BUFFER_OVERFLOW_ERROR: Returns number of UChars for preflighting. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Number of UChars in the data. Does not include a trailing NUL.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001971">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01208">1208</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="acaf57d3fd11db28583a36df05ec02295"></a><!-- doxytag: member="utext.h::UTextFuncs" ref="acaf57d3fd11db28583a36df05ec02295" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="structUTextFuncs.html">UTextFuncs</a> <a class="el" href="structUTextFuncs.html">UTextFuncs</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function dispatch table for <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="structUTextFuncs.html" title="(public) Function dispatch table for UText.">UTextFuncs</a> </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01469">1469</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="ab14d770b0feb53e5c4677f998e6b5ad0"></a><!-- doxytag: member="utext.h::UTextMapNativeIndexToUTF16" ref="ab14d770b0feb53e5c4677f998e6b5ad0" args="(const UText *ut, int64_t nativeIndex)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int32_t <a class="el" href="utext_8h.html#ab14d770b0feb53e5c4677f998e6b5ad0">UTextMapNativeIndexToUTF16</a>(const <a class="el" href="structUText.html">UText</a> *ut, int64_t nativeIndex)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.mapIndexToUTF16(). </p>
<p>Map from a native index to a UChar offset within a text chunk. Behavior is undefined if the native index does not fall within the current chunk.</p>
<p>This function is required only for text providers that do not use native UTF-16 indexes.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> containing the text chunk. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeIndex</em> </td><td>Absolute (native) text index, chunk->start<=index<=chunk->limit. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Chunk-relative UTF-16 offset corresponding to the specified native index.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001975">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01315">1315</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="aa78b6ae4b98958554b7ee15de57e9c30"></a><!-- doxytag: member="utext.h::UTextMapOffsetToNative" ref="aa78b6ae4b98958554b7ee15de57e9c30" args="(const UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int64_t <a class="el" href="utext_8h.html#aa78b6ae4b98958554b7ee15de57e9c30">UTextMapOffsetToNative</a>(const <a class="el" href="structUText.html">UText</a> *ut)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.mapOffsetToNative(). </p>
<p>Map from the current UChar offset within the current text chunk to the corresponding native index in the original source text.</p>
<p>This is required only for text providers that do not use native UTF-16 indexes.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a>. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Absolute (native) index corresponding to chunkOffset in the current chunk. The returned native index should always be to a code point boundary.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001974">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01297">1297</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a36bad470545b3183fff611c91312cc10"></a><!-- doxytag: member="utext.h::UTextNativeLength" ref="a36bad470545b3183fff611c91312cc10" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int64_t <a class="el" href="utext_8h.html#a36bad470545b3183fff611c91312cc10">UTextNativeLength</a>(<a class="el" href="structUText.html">UText</a> *ut)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.nativeLength(). </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> to get the length of. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the length, in the native units of the original text string. </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="structUText.html" title="UText struct.">UText</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001969">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01150">1150</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a0a84b5d0d434b0f1f71f77841cac3d97"></a><!-- doxytag: member="utext.h::UTextReplace" ref="a0a84b5d0d434b0f1f71f77841cac3d97" args="(UText *ut, int64_t nativeStart, int64_t nativeLimit, const UChar *replacementText, int32_t replacmentLength, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int32_t <a class="el" href="utext_8h.html#a0a84b5d0d434b0f1f71f77841cac3d97">UTextReplace</a>(<a class="el" href="structUText.html">UText</a> *ut, int64_t nativeStart, int64_t nativeLimit, const <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> *replacementText, int32_t replacmentLength, <a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> *status)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Function type declaration for UText.replace(). </p>
<p>Replace a range of the original text with a replacement text.</p>
<p>Leaves the current iteration position at the position following the newly inserted replacement text.</p>
<p>This function need only be implemented on <a class="el" href="structUText.html" title="UText struct.">UText</a> types that support writing.</p>
<p>When using this function, there should be only a single <a class="el" href="structUText.html" title="UText struct.">UText</a> opened onto the underlying native text string. The function is responsible for updating the text chunk within the <a class="el" href="structUText.html" title="UText struct.">UText</a> to reflect the updated iteration position, taking into account any changes to the underlying string's structure caused by the replace operation.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> representing the text to be operated on. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeStart</em> </td><td>the index of the start of the region to be replaced </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeLimit</em> </td><td>the index of the character following the region to be replaced. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>replacementText</em> </td><td>pointer to the replacement text </td></tr>
<tr><td valign="top"></td><td valign="top"><em>replacmentLength</em> </td><td>length of the replacement text in UChars, or -1 if the text is NUL terminated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>receives any error status. Possible errors include U_NO_WRITE_PERMISSION</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The signed number of (native) storage units by which the length of the text expanded or contracted.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001972">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01243">1243</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<hr/><h2>Enumeration Type Documentation</h2>
<a class="anchor" id="a05589fbab0657f08285ebdfe93f5ec9e"></a><!-- doxytag: member="utext.h::@13" ref="a05589fbab0657f08285ebdfe93f5ec9e" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">anonymous enum</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="structUText.html" title="UText struct.">UText</a> provider properties (bit field indexes). </p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="structUText.html" title="UText struct.">UText</a> </dd></dl>
<dl class="stable"><dt><b>Stable:</b></dt><dd>ICU 3.4 </dd></dl>
<dl><dt><b>Enumerator: </b></dt><dd><table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><em><a class="anchor" id="a05589fbab0657f08285ebdfe93f5ec9ea752c07f9df260b5b0e234e15eab97f9f"></a><!-- doxytag: member="UTEXT_PROVIDER_LENGTH_IS_EXPENSIVE" ref="a05589fbab0657f08285ebdfe93f5ec9ea752c07f9df260b5b0e234e15eab97f9f" args="" -->UTEXT_PROVIDER_LENGTH_IS_EXPENSIVE</em> </td><td>
<p>It is potentially time consuming for the provider to determine the length of the text. </p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001981">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="a05589fbab0657f08285ebdfe93f5ec9ea52bb5c9cacd1f46eb87a856c71c073be"></a><!-- doxytag: member="UTEXT_PROVIDER_STABLE_CHUNKS" ref="a05589fbab0657f08285ebdfe93f5ec9ea52bb5c9cacd1f46eb87a856c71c073be" args="" -->UTEXT_PROVIDER_STABLE_CHUNKS</em> </td><td>
<p>Text chunks remain valid and usable until the text object is modified or deleted, not just until the next time the access() function is called (which is the default). </p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001982">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="a05589fbab0657f08285ebdfe93f5ec9eac67ce6ecf6bf959645e282f7194fbe3b"></a><!-- doxytag: member="UTEXT_PROVIDER_WRITABLE" ref="a05589fbab0657f08285ebdfe93f5ec9eac67ce6ecf6bf959645e282f7194fbe3b" args="" -->UTEXT_PROVIDER_WRITABLE</em> </td><td>
<p>The provider supports modifying the text via the replace() and copy() functions. </p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classReplaceable.html" title="Replaceable is an abstract base class representing a string of characters that supports...">Replaceable</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001983">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="a05589fbab0657f08285ebdfe93f5ec9ea40c5cd24aea472f3752b4833b9ce63ca"></a><!-- doxytag: member="UTEXT_PROVIDER_HAS_META_DATA" ref="a05589fbab0657f08285ebdfe93f5ec9ea40c5cd24aea472f3752b4833b9ce63ca" args="" -->UTEXT_PROVIDER_HAS_META_DATA</em> </td><td>
<p>There is meta data associated with the text. </p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classReplaceable.html#ad4ae052a7be93bb0a69a6a55ff45ca43" title="Returns true if this object contains metadata.">Replaceable::hasMetaData()</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001984">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="a05589fbab0657f08285ebdfe93f5ec9ea75695072a896ec104b5d77598a7429f7"></a><!-- doxytag: member="UTEXT_PROVIDER_OWNS_TEXT" ref="a05589fbab0657f08285ebdfe93f5ec9ea75695072a896ec104b5d77598a7429f7" args="" -->UTEXT_PROVIDER_OWNS_TEXT</em> </td><td>
<p>Text provider owns the text storage. </p>
<p>Generally occurs as the result of a deep clone of the <a class="el" href="structUText.html" title="UText struct.">UText</a>. When closing the <a class="el" href="structUText.html" title="UText struct.">UText</a>, the associated text must also be closed/deleted/freed/ whatever is appropriate. </p>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001985">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
</td></tr>
</table>
</dd>
</dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01064">1064</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<a class="anchor" id="a16af7b253440dadd46a80a4b9fddba4d"></a><!-- doxytag: member="utext.h::@14" ref="a16af7b253440dadd46a80a4b9fddba4d" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">anonymous enum</td>
</tr>
</table>
</div>
<div class="memdoc">
<dl class="internal"><dt><b>Internal:</b></dt><dd>Do not use. This API is for internal use only. Value used to help identify correctly initialized <a class="el" href="structUText.html" title="UText struct.">UText</a> structs. Note: must be publicly visible so that UTEXT_INITIALIZER can access it. </dd></dl>
<p>Definition at line <a class="el" href="utext_8h_source.html#l01700">1700</a> of file <a class="el" href="utext_8h_source.html">utext.h</a>.</p>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="a3f1953865cbbd5c2846166e802701a08"></a><!-- doxytag: member="utext.h::utext_caseCompare" ref="a3f1953865cbbd5c2846166e802701a08" args="(UText *s1, int32_t length1, UText *s2, int32_t length2, uint32_t options, UErrorCode *pErrorCode)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t utext_caseCompare </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>length1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s2</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>length2</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t </td>
<td class="paramname"> <em>options</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>pErrorCode</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Compare two UTexts case-insensitively using full case folding. </p>
<p>The comparison begins at each source text's iteration position. The iteration position of each <a class="el" href="structUText.html" title="UText struct.">UText</a> will be left following the last character compared.</p>
<p>The comparison is done in code point order; this is because the characters in a <a class="el" href="structUText.html" title="UText struct.">UText</a> are accessed one code point at a time, and may not be from a UTF-16 context.</p>
<p>This functions works with strings of different explicitly specified lengths unlike the ANSI C-like <a class="el" href="ustring_8h.html#abdb8af67ab5198b9db020afa9c3114b3" title="Compare two Unicode strings for bitwise equality (code unit order).">u_strcmp()</a> and <a class="el" href="ustring_8h.html#a95643325eec27e247d28531f3c68600b" title="Compare the first count UChars of each buffer.">u_memcmp()</a> etc. A length argument of -1 signifies that as much of the string should be used as is necessary to compare with the other string. If both length arguments are -1, the entire remaining portionss of both strings are used.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>s1</em> </td><td>First source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length1</em> </td><td>Length of first source string in UTF-32 code points.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>s2</em> </td><td>Second source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length2</em> </td><td>Length of second source string in UTF-32 code points.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>options</em> </td><td>A bit set of options:</p>
<ul>
<li>U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code point order with default case folding.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<ul>
<li>U_FOLD_CASE_EXCLUDE_SPECIAL_I</li>
</ul>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>pErrorCode</em> </td><td>Must be a valid pointer to an error code value, which must not indicate a failure before the function call.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><0 or 0 or >0 as usual for string comparisons</dd></dl>
<dl class="internal"><dt><b><a class="el" href="internal.html#_internal000107">Internal:</a></b></dt><dd>Do not use. This API is for internal use only. ICU 4.4 technology preview </dd></dl>
</div>
</div>
<a class="anchor" id="a0bf112f899232a46c0c02333d44b2289"></a><!-- doxytag: member="utext.h::utext_caseCompareNativeLimit" ref="a0bf112f899232a46c0c02333d44b2289" args="(UText *s1, int64_t limit1, UText *s2, int64_t limit2, uint32_t options, UErrorCode *pErrorCode)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t utext_caseCompareNativeLimit </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>limit1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s2</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>limit2</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t </td>
<td class="paramname"> <em>options</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>pErrorCode</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Compare two UTexts case-insensitively using full case folding. </p>
<p>The comparison begins at each source text's iteration position. The iteration position of each <a class="el" href="structUText.html" title="UText struct.">UText</a> will be left following the last character compared. This method differs from utext_caseCompare in that it accepts native limits rather than lengths for each string.</p>
<p>The comparison is done in code point order; this is because the characters in a <a class="el" href="structUText.html" title="UText struct.">UText</a> are accessed one code point at a time, and may not be from a UTF-16 context.</p>
<p>This functions works with strings of different explicitly specified lengths unlike the ANSI C-like <a class="el" href="ustring_8h.html#abdb8af67ab5198b9db020afa9c3114b3" title="Compare two Unicode strings for bitwise equality (code unit order).">u_strcmp()</a> and <a class="el" href="ustring_8h.html#a95643325eec27e247d28531f3c68600b" title="Compare the first count UChars of each buffer.">u_memcmp()</a> etc. A limit argument of -1 signifies that as much of the string should be used as is necessary to compare with the other string. If both length arguments are -1, the entire remaining portionss of both strings are used.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>s1</em> </td><td>First source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>limit1</em> </td><td>Native index of the last character in the first source string to be considered.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>s2</em> </td><td>Second source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>limit2</em> </td><td>Native index of the last character in the second source string to be considered.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>options</em> </td><td>A bit set of options:</p>
<ul>
<li>U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code point order with default case folding.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<ul>
<li>U_FOLD_CASE_EXCLUDE_SPECIAL_I</li>
</ul>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>pErrorCode</em> </td><td>Must be a valid pointer to an error code value, which must not indicate a failure before the function call.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><0 or 0 or >0 as usual for string comparisons</dd></dl>
<dl class="internal"><dt><b><a class="el" href="internal.html#_internal000108">Internal:</a></b></dt><dd>Do not use. This API is for internal use only. ICU 4.4 technology preview </dd></dl>
</div>
</div>
<a class="anchor" id="aab911e6df41b5e5a90fd09d2f0aa4fbc"></a><!-- doxytag: member="utext.h::utext_char32At" ref="aab911e6df41b5e5a90fd09d2f0aa4fbc" args="(UText *ut, int64_t nativeIndex)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> utext_char32At </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeIndex</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the code point at the requested index, or U_SENTINEL (-1) if it is out of bounds. </p>
<p>If the specified index points to the interior of a multi-unit character - one of the trail bytes of a UTF-8 sequence, for example - the complete code point will be returned.</p>
<p>The iteration position will be set to the start of the returned code point.</p>
<p>This function is roughly equivalent to the the sequence utext_setNativeIndex(index); <a class="el" href="utext_8h.html#a890bfd8f4c97a85bb70a22eabb34b716" title="Get the code point at the current iteration position, or U_SENTINEL (-1) if the iteration...">utext_current32()</a>; (There is a subtle difference if the index is out of bounds by being less than zero - utext_setNativeIndex(negative value) sets the index to zero, after which utext_current() will return the char at zero. utext_char32At(negative index), on the other hand, will return the U_SENTINEL value of -1.)</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeIndex</em> </td><td>the native index of the character to be accessed. If the index points to other than the first unit of a multi-unit character, it will be adjusted to the start of the character. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the code point at the specified index. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001947">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a8732a0c34ee4764c08f70b7a8d7ca4d4"></a><!-- doxytag: member="utext.h::utext_clone" ref="a8732a0c34ee4764c08f70b7a8d7ca4d4" args="(UText *dest, const UText *src, UBool deep, UBool readOnly, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structUText.html">UText</a>* utext_clone </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>dest</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>src</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td>
<td class="paramname"> <em>deep</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td>
<td class="paramname"> <em>readOnly</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Clone a <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<p>This is much like opening a <a class="el" href="structUText.html" title="UText struct.">UText</a> where the source text is itself another <a class="el" href="structUText.html" title="UText struct.">UText</a>.</p>
<p>A deep clone will copy both the <a class="el" href="structUText.html" title="UText struct.">UText</a> data structures and the underlying text. The original and cloned <a class="el" href="structUText.html" title="UText struct.">UText</a> will operate completely independently; modifications made to the text in one will not affect the other. Text providers are not required to support deep clones. The user of clone() must check the status return and be prepared to handle failures.</p>
<p>The standard <a class="el" href="structUText.html" title="UText struct.">UText</a> implementations for UTF8, UChar *, <a class="el" href="classUnicodeString.html" title="UnicodeString is a string class that stores Unicode characters directly and provides...">UnicodeString</a> and <a class="el" href="classReplaceable.html" title="Replaceable is an abstract base class representing a string of characters that supports...">Replaceable</a> all support deep cloning.</p>
<p>The <a class="el" href="structUText.html" title="UText struct.">UText</a> returned from a deep clone will be writable, assuming that the text provider is able to support writing, even if the source <a class="el" href="structUText.html" title="UText struct.">UText</a> had been made non-writable by means of UText_freeze().</p>
<p>A shallow clone replicates only the <a class="el" href="structUText.html" title="UText struct.">UText</a> data structures; it does not make a copy of the underlying text. Shallow clones can be used as an efficient way to have multiple iterators active in a single text string that is not being modified.</p>
<p>A shallow clone operation will not fail, barring truly exceptional conditions such as memory allocation failures.</p>
<p>Shallow <a class="el" href="structUText.html" title="UText struct.">UText</a> clones should be avoided if the <a class="el" href="structUText.html" title="UText struct.">UText</a> functions that modify the text are expected to be used, either on the original or the cloned <a class="el" href="structUText.html" title="UText struct.">UText</a>. Any such modifications can cause unpredictable behavior. Read Only shallow clones provide some protection against errors of this type by disabling text modification via the cloned <a class="el" href="structUText.html" title="UText struct.">UText</a>.</p>
<p>A shallow clone made with the readOnly parameter == FALSE will preserve the <a class="el" href="utext_8h.html#af67295033b5dc1b2951b8b05e5ce9222" title="Return TRUE if the text can be written (modified) with utext_replace() or utext_copy()...">utext_isWritable()</a> state of the source object. Note, however, that write operations must be avoided while more than one <a class="el" href="structUText.html" title="UText struct.">UText</a> exists that refer to the same underlying text.</p>
<p>A <a class="el" href="structUText.html" title="UText struct.">UText</a> and its clone may be safely concurrently accessed by separate threads. This is true for read access only with shallow clones, and for both read and write access with deep clones. It is the responsibility of the Text Provider to ensure that this thread safety constraint is met.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>A <a class="el" href="structUText.html" title="UText struct.">UText</a> struct to be filled in with the result of the clone operation, or NULL if the clone function should heap-allocate a new <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. If non-NULL, must refer to an already existing <a class="el" href="structUText.html" title="UText struct.">UText</a>, which will then be reset to become the clone. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>src</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> to be cloned. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>deep</em> </td><td>TRUE to request a deep clone, FALSE for a shallow clone. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>readOnly</em> </td><td>TRUE to request that the cloned <a class="el" href="structUText.html" title="UText struct.">UText</a> have read only access to the underlying text.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR will be returned if the text provider is unable to clone the original text. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The newly created clone, or NULL if the clone operation failed. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001943">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a303eb28b0f98498dfcb063e05ab2695c"></a><!-- doxytag: member="utext.h::utext_close" ref="a303eb28b0f98498dfcb063e05ab2695c" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structUText.html">UText</a>* utext_close </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Close function for <a class="el" href="structUText.html" title="UText struct.">UText</a> instances. </p>
<p>Cleans up, releases any resources being held by an open <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<p>If the <a class="el" href="structUText.html" title="UText struct.">UText</a> was originally allocated by one of the utext_open functions, the storage associated with the utext will also be freed. If the <a class="el" href="structUText.html" title="UText struct.">UText</a> storage originated with the application, as it would with a local or static instance, the storage will not be deleted.</p>
<p>An open <a class="el" href="structUText.html" title="UText struct.">UText</a> can be reset to refer to new string by using one of the utext_open() functions without first closing the <a class="el" href="structUText.html" title="UText struct.">UText</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> to be closed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>NULL if the <a class="el" href="structUText.html" title="UText struct.">UText</a> struct was deleted by the close. If the <a class="el" href="structUText.html" title="UText struct.">UText</a> struct was originally provided by the caller to the open function, it is returned by this function, and may be safely used again in a subsequent utext_open.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001940">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a5143c3dc59cf1614a50a5873fd49171f"></a><!-- doxytag: member="utext.h::utext_compare" ref="a5143c3dc59cf1614a50a5873fd49171f" args="(UText *s1, int32_t length1, UText *s2, int32_t length2)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t utext_compare </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>length1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s2</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>length2</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Compare two UTexts (binary order). </p>
<p>The comparison begins at each source text's iteration position. The iteration position of each <a class="el" href="structUText.html" title="UText struct.">UText</a> will be left following the last character compared.</p>
<p>The comparison is done in code point order; unlike u_strCompare, you cannot choose to use code unit order. This is because the characters in a <a class="el" href="structUText.html" title="UText struct.">UText</a> are accessed one code point at a time, and may not be from a UTF-16 context.</p>
<p>This functions works with strings of different explicitly specified lengths unlike the ANSI C-like <a class="el" href="ustring_8h.html#abdb8af67ab5198b9db020afa9c3114b3" title="Compare two Unicode strings for bitwise equality (code unit order).">u_strcmp()</a> and <a class="el" href="ustring_8h.html#a95643325eec27e247d28531f3c68600b" title="Compare the first count UChars of each buffer.">u_memcmp()</a> etc. A length argument of -1 signifies that as much of the string should be used as is necessary to compare with the other string. If both length arguments are -1, the entire remaining portionss of both strings are used.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>s1</em> </td><td>First source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length1</em> </td><td>Length of first source string in UTF-32 code points.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>s2</em> </td><td>Second source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length2</em> </td><td>Length of second source string in UTF-32 code points.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><0 or 0 or >0 as usual for string comparisons</dd></dl>
<dl class="internal"><dt><b><a class="el" href="internal.html#_internal000105">Internal:</a></b></dt><dd>Do not use. This API is for internal use only. ICU 4.4 technology preview </dd></dl>
</div>
</div>
<a class="anchor" id="adeaed071bf866b2af77cc5708c98e589"></a><!-- doxytag: member="utext.h::utext_compareNativeLimit" ref="adeaed071bf866b2af77cc5708c98e589" args="(UText *s1, int64_t limit1, UText *s2, int64_t limit2)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t utext_compareNativeLimit </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>limit1</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>s2</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>limit2</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Compare two UTexts (binary order). </p>
<p>The comparison begins at each source text's iteration position. The iteration position of each <a class="el" href="structUText.html" title="UText struct.">UText</a> will be left following the last character compared. This method differs from utext_compare in that it accepts native limits rather than lengths for each string.</p>
<p>The comparison is done in code point order; unlike u_strCompare, you cannot choose to use code unit order. This is because the characters in a <a class="el" href="structUText.html" title="UText struct.">UText</a> are accessed one code point at a time, and may not be from a UTF-16 context.</p>
<p>This functions works with strings of different explicitly specified lengths unlike the ANSI C-like <a class="el" href="ustring_8h.html#abdb8af67ab5198b9db020afa9c3114b3" title="Compare two Unicode strings for bitwise equality (code unit order).">u_strcmp()</a> and <a class="el" href="ustring_8h.html#a95643325eec27e247d28531f3c68600b" title="Compare the first count UChars of each buffer.">u_memcmp()</a> etc. A limit argument of -1 signifies that as much of the string should be used as is necessary to compare with the other string. If both limit arguments are -1, the entire remaining portionss of both strings are used.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>s1</em> </td><td>First source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>limit1</em> </td><td>Native index of the last character in the first source string to be considered.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>s2</em> </td><td>Second source string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>limit2</em> </td><td>Native index of the last character in the second source string to be considered.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><0 or 0 or >0 as usual for string comparisons</dd></dl>
<dl class="internal"><dt><b><a class="el" href="internal.html#_internal000106">Internal:</a></b></dt><dd>Do not use. This API is for internal use only. ICU 4.4 technology preview </dd></dl>
</div>
</div>
<a class="anchor" id="abe74b66b8da9b9de17ea7e59af395c53"></a><!-- doxytag: member="utext.h::utext_copy" ref="abe74b66b8da9b9de17ea7e59af395c53" args="(UText *ut, int64_t nativeStart, int64_t nativeLimit, int64_t destIndex, UBool move, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void utext_copy </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeStart</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeLimit</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>destIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> </td>
<td class="paramname"> <em>move</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Copy or move a substring from one position to another within the text, while retaining any metadata associated with the text. </p>
<p>This function is used to duplicate or reorder substrings. The destination index must not overlap the source range.</p>
<p>The text to be copied or moved is inserted at destIndex; it does not replace or overwrite any existing text.</p>
<p>The iteration position is left following the newly inserted text at the destination position.</p>
<p>This function is only available on <a class="el" href="structUText.html" title="UText struct.">UText</a> types that support writing, that is, ones where <a class="el" href="utext_8h.html#af67295033b5dc1b2951b8b05e5ce9222" title="Return TRUE if the text can be written (modified) with utext_replace() or utext_copy()...">utext_isWritable()</a> returns TRUE.</p>
<p>When using this function, there should be only a single <a class="el" href="structUText.html" title="UText struct.">UText</a> opened onto the underlying native text string. Behavior after a copy operation on a <a class="el" href="structUText.html" title="UText struct.">UText</a> is undefined in any other additional UTexts that refer to the modified string.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> representing the text to be operated on. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeStart</em> </td><td>The native index of the start of the region to be copied or moved </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeLimit</em> </td><td>The native index of the character position following the region to be copied. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>destIndex</em> </td><td>The native destination index to which the source substring is copied or moved. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>move</em> </td><td>If TRUE, then the substring is moved, not copied/duplicated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>receives any error status. Possible errors include U_NO_WRITE_PERMISSION</td></tr>
</table>
</dd>
</dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001965">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a890bfd8f4c97a85bb70a22eabb34b716"></a><!-- doxytag: member="utext.h::utext_current32" ref="a890bfd8f4c97a85bb70a22eabb34b716" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> utext_current32 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the code point at the current iteration position, or U_SENTINEL (-1) if the iteration has reached the end of the input text. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the Unicode code point at the current iterator position. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001948">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a592a289ae040b2e610e9aaa9032ce276"></a><!-- doxytag: member="utext.h::utext_equals" ref="a592a289ae040b2e610e9aaa9032ce276" args="(const UText *a, const UText *b)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> utext_equals </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>a</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>b</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Compare two <a class="el" href="structUText.html" title="UText struct.">UText</a> objects for equality. </p>
<p>UTexts are equal if they are iterating over the same text, and have the same iteration position within the text. If either or both of the parameters are NULL, the comparison is FALSE.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>a</em> </td><td>The first of the two UTexts to compare. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>b</em> </td><td>The other <a class="el" href="structUText.html" title="UText struct.">UText</a> to be compared. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>TRUE if the two UTexts are equal. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001944">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
</div>
</div>
<a class="anchor" id="aec0833241ef75e474f3dbf4dcf3be9c3"></a><!-- doxytag: member="utext.h::utext_extract" ref="aec0833241ef75e474f3dbf4dcf3be9c3" args="(UText *ut, int64_t nativeStart, int64_t nativeLimit, UChar *dest, int32_t destCapacity, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t utext_extract </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeStart</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeLimit</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> * </td>
<td class="paramname"> <em>dest</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>destCapacity</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Extract text from a <a class="el" href="structUText.html" title="UText struct.">UText</a> into a UChar buffer. </p>
<p>The range of text to be extracted is specified in the native indices of the <a class="el" href="structUText.html" title="UText struct.">UText</a> provider. These may not necessarily be UTF-16 indices. </p>
<p>The size (number of 16 bit UChars) of the data to be extracted is returned. The full number of UChars is returned, even when the extracted text is truncated because the specified buffer size is too small. </p>
<p>The extracted string will (if you are a user) / must (if you are a text provider) be NUL-terminated if there is sufficient space in the destination buffer. This terminating NUL is not included in the returned length. </p>
<p>The iteration index is left at the position following the last extracted character.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> from which to extract data. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeStart</em> </td><td>the native index of the first character to extract.\ If the specified index is out of range, it will be pinned to to be within 0 <= index <= textLength </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeLimit</em> </td><td>the native string index of the position following the last character to extract. If the specified index is out of range, it will be pinned to to be within 0 <= index <= textLength. nativeLimit must be >= nativeStart. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>the UChar (UTF-16) buffer into which the extracted text is placed </td></tr>
<tr><td valign="top"></td><td valign="top"><em>destCapacity</em> </td><td>The size, in UChars, of the destination buffer. May be zero for precomputing the required size. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>receives any error status. U_BUFFER_OVERFLOW_ERROR: the extracted text was truncated because the buffer was too small. Returns number of UChars for preflighting. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Number of UChars in the data to be extracted. Does not include a trailing NUL.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001957">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a1ea9abacabf9f48914104dba66d932ff"></a><!-- doxytag: member="utext.h::utext_freeze" ref="a1ea9abacabf9f48914104dba66d932ff" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void utext_freeze </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Freeze a <a class="el" href="structUText.html" title="UText struct.">UText</a>. This prevents any modification to the underlying text itself by means of functions operating on this <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<p>Once frozen, a <a class="el" href="structUText.html" title="UText struct.">UText</a> can not be unfrozen. The intent is to ensure that a the text underlying a frozen <a class="el" href="structUText.html" title="UText struct.">UText</a> wrapper cannot be modified via that <a class="el" href="structUText.html" title="UText struct.">UText</a>. </p>
<p>Caution: freezing a <a class="el" href="structUText.html" title="UText struct.">UText</a> will disable changes made via the specific frozen <a class="el" href="structUText.html" title="UText struct.">UText</a> wrapper only; it will not have any effect on the ability to directly modify the text by bypassing the <a class="el" href="structUText.html" title="UText struct.">UText</a>. Any such backdoor modifications are always an error while <a class="el" href="structUText.html" title="UText struct.">UText</a> access is occuring because the underlying text can get out of sync with UText's buffering. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> to be frozen. </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="utext_8h.html#af67295033b5dc1b2951b8b05e5ce9222" title="Return TRUE if the text can be written (modified) with utext_replace() or utext_copy()...">utext_isWritable()</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001966">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
</div>
</div>
<a class="anchor" id="acd28c25814787d3d1620e3edb8f917fd"></a><!-- doxytag: member="utext.h::utext_getNativeIndex" ref="acd28c25814787d3d1620e3edb8f917fd" args="(const UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int64_t utext_getNativeIndex </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the current iterator position, which can range from 0 to the length of the text. </p>
<p>The position is a native index into the input text, in whatever format it may have (possibly UTF-8 for example), and may not always be the same as the corresponding UChar (UTF-16) index. The returned position will always be aligned to a code point boundary.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the current index position, in the native units of the text provider. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001953">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a2c703c15aa63fc6555d50feec4f6b3c6"></a><!-- doxytag: member="utext.h::utext_getPreviousNativeIndex" ref="a2c703c15aa63fc6555d50feec4f6b3c6" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int64_t utext_getPreviousNativeIndex </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the native index of the character preceeding the current position. </p>
<p>If the iteration position is already at the start of the text, zero is returned. The value returned is the same as that obtained from the following sequence, but without the side effect of changing the iteration position.</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="structUText.html" title="UText struct.">UText</a> *ut = whatever;
...
utext_previous(ut)
<a class="code" href="utext_8h.html#acd28c25814787d3d1620e3edb8f917fd" title="Get the current iterator position, which can range from 0 to the length of the text...">utext_getNativeIndex</a>(ut);
</pre></div><p>This function is most useful during forwards iteration, where it will get the native index of the character most recently returned from utext_next().</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the native index of the character preceeding the current index position, or zero if the current position is at the start of the text. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001956">Stable:</a></b></dt><dd>ICU 3.6 </dd></dl>
</div>
</div>
<a class="anchor" id="a5ca583f3d6592f6e4d00bd43a9bb4952"></a><!-- doxytag: member="utext.h::utext_hasMetaData" ref="a5ca583f3d6592f6e4d00bd43a9bb4952" args="(const UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> utext_hasMetaData </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Test whether there is meta data associated with the text. </p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classReplaceable.html#ad4ae052a7be93bb0a69a6a55ff45ca43" title="Returns true if this object contains metadata.">Replaceable::hasMetaData()</a></dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>The <a class="el" href="structUText.html" title="UText struct.">UText</a> to be tested </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>TRUE if the underlying text includes meta data. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001963">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a18dd4010f0d9fbe9c920f3ce954990ed"></a><!-- doxytag: member="utext.h::utext_isLengthExpensive" ref="a18dd4010f0d9fbe9c920f3ce954990ed" args="(const UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> utext_isLengthExpensive </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return TRUE if calculating the length of the text could be expensive. </p>
<p>Finding the length of NUL terminated strings is considered to be expensive.</p>
<p>Note that the value of this function may change as the result of other operations on a <a class="el" href="structUText.html" title="UText struct.">UText</a>. Once the length of a string has been discovered, it will no longer be expensive to report it.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>TRUE if determining the length of the text could be time consuming. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001946">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="af67295033b5dc1b2951b8b05e5ce9222"></a><!-- doxytag: member="utext.h::utext_isWritable" ref="af67295033b5dc1b2951b8b05e5ce9222" args="(const UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> utext_isWritable </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return TRUE if the text can be written (modified) with <a class="el" href="utext_8h.html#aa781cea4987dda8a7c5f0351e311bf07" title="Replace a range of the original text with a replacement text.">utext_replace()</a> or <a class="el" href="utext_8h.html#abe74b66b8da9b9de17ea7e59af395c53" title="Copy or move a substring from one position to another within the text, while retaining...">utext_copy()</a>. </p>
<p>For the text to be writable, the text provider must be of a type that supports writing and the <a class="el" href="structUText.html" title="UText struct.">UText</a> must not be frozen.</p>
<p>Attempting to modify text when utext_isWriteable() is FALSE will fail - the text will not be modified, and an error will be returned from the function that attempted the modification.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> to be tested. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>TRUE if the text is modifiable.</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="utext_8h.html#a1ea9abacabf9f48914104dba66d932ff">utext_freeze()</a> </dd>
<dd>
<a class="el" href="utext_8h.html#aa781cea4987dda8a7c5f0351e311bf07" title="Replace a range of the original text with a replacement text.">utext_replace()</a> </dd>
<dd>
<a class="el" href="utext_8h.html#abe74b66b8da9b9de17ea7e59af395c53" title="Copy or move a substring from one position to another within the text, while retaining...">utext_copy()</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001962">Stable:</a></b></dt><dd>ICU 3.4</dd></dl>
</div>
</div>
<a class="anchor" id="af91afb68d5059ec704d8d6969288c00d"></a><!-- doxytag: member="utext.h::utext_moveIndex32" ref="af91afb68d5059ec704d8d6969288c00d" args="(UText *ut, int32_t delta)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a349ef00011f20ccd1d3b424445681aa5">UBool</a> utext_moveIndex32 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>delta</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Move the iterator postion by delta code points. </p>
<p>The number of code points is a signed number; a negative delta will move the iterator backwards, towards the start of the text. </p>
<p>The index is moved by <code>delta</code> code points forward or backward, but no further backward than to 0 and no further forward than to <a class="el" href="utext_8h.html#ab6a809d8168c1ccf30746cd57234a59e" title="Get the length of the text.">utext_nativeLength()</a>. The resulting index value will be in between 0 and length, inclusive.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>delta</em> </td><td>the signed number of code points to move the iteration position. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>TRUE if the position could be moved the requested number of positions while staying within the range [0 - text length]. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001955">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="ab6a809d8168c1ccf30746cd57234a59e"></a><!-- doxytag: member="utext.h::utext_nativeLength" ref="ab6a809d8168c1ccf30746cd57234a59e" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int64_t utext_nativeLength </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the length of the text. </p>
<p>Depending on the characteristics of the underlying text representation, this may be expensive. </p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="utext_8h.html#a18dd4010f0d9fbe9c920f3ce954990ed" title="Return TRUE if calculating the length of the text could be expensive.">utext_isLengthExpensive()</a></dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the length of the text, expressed in native units.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001945">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="ad4c8e3ba851a3482b2c77cc58cff9ad0"></a><!-- doxytag: member="utext.h::utext_next32" ref="ad4c8e3ba851a3482b2c77cc58cff9ad0" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> utext_next32 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the code point at the current iteration position of the <a class="el" href="structUText.html" title="UText struct.">UText</a>, and advance the position to the first index following the character. </p>
<p>If the position is at the end of the text (the index following the last character, which is also the length of the text), return U_SENTINEL (-1) and do not advance the index.</p>
<p>This is a post-increment operation.</p>
<p>An inline macro version of this function, <a class="el" href="utext_8h.html#aa4b973aeeb5f10f8aec454545f85b6a2" title="inline version of utext_next32(), for performance-critical situations.">UTEXT_NEXT32()</a>, is available for performance critical use.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the Unicode code point at the iteration position. </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="utext_8h.html#aa4b973aeeb5f10f8aec454545f85b6a2" title="inline version of utext_next32(), for performance-critical situations.">UTEXT_NEXT32</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001949">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a819b23625de643f71280c076feac31a7"></a><!-- doxytag: member="utext.h::utext_next32From" ref="a819b23625de643f71280c076feac31a7" args="(UText *ut, int64_t nativeIndex)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> utext_next32From </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeIndex</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the iteration index and return the code point at that index. </p>
<p>Leave the iteration index at the start of the following code point.</p>
<p>This function is the most efficient and convenient way to begin a forward iteration. The results are identical to the those from the sequence </p>
<div class="fragment"><pre class="fragment"> utext_setIndex();
<a class="code" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0" title="Get the code point at the current iteration position of the UText, and advance the...">utext_next32</a>();
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeIndex</em> </td><td>Iteration index, in the native units of the text provider. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Code point which starts at or before index, or U_SENTINEL (-1) if it is out of bounds. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001951">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="adf311525bdd2a7f155bbe5cbb4c4de15"></a><!-- doxytag: member="utext.h::utext_openUChars" ref="adf311525bdd2a7f155bbe5cbb4c4de15" args="(UText *ut, const UChar *s, int64_t length, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structUText.html">UText</a>* utext_openUChars </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> * </td>
<td class="paramname"> <em>s</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Open a read-only <a class="el" href="structUText.html" title="UText struct.">UText</a> for UChar * string. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>Pointer to a <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. If NULL, a new <a class="el" href="structUText.html" title="UText struct.">UText</a> will be created. If non-NULL, must refer to an initialized <a class="el" href="structUText.html" title="UText struct.">UText</a> struct, which will then be reset to reference the specified UChar string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>s</em> </td><td>A UChar (UTF-16) string </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>The number of UChars in the input string, or -1 if the string is zero terminated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>Errors are returned here. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A pointer to the <a class="el" href="structUText.html" title="UText struct.">UText</a>. If a pre-allocated <a class="el" href="structUText.html" title="UText struct.">UText</a> was provided, it will always be used and returned. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001942">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a32e9e14644d140c3501a7a09e7ad5864"></a><!-- doxytag: member="utext.h::utext_openUTF8" ref="a32e9e14644d140c3501a7a09e7ad5864" args="(UText *ut, const char *s, int64_t length, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structUText.html">UText</a>* utext_openUTF8 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>s</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Open a read-only <a class="el" href="structUText.html" title="UText struct.">UText</a> implementation for UTF-8 strings. </p>
Any invalid UTF-8 in the input will be handled in this way:
a sequence of bytes that has the form of a truncated, but otherwise valid,
UTF-8 sequence will be replaced by a single unicode replacement character, \uFFFD.
Any other illegal bytes will each be replaced by a \uFFFD.
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>Pointer to a <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. If NULL, a new <a class="el" href="structUText.html" title="UText struct.">UText</a> will be created. If non-NULL, must refer to an initialized <a class="el" href="structUText.html" title="UText struct.">UText</a> struct, which will then be reset to reference the specified UTF-8 string. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>s</em> </td><td>A UTF-8 string. Must not be NULL. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>length</em> </td><td>The length of the UTF-8 string in bytes, or -1 if the string is zero terminated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>Errors are returned here. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>A pointer to the <a class="el" href="structUText.html" title="UText struct.">UText</a>. If a pre-allocated <a class="el" href="structUText.html" title="UText struct.">UText</a> was provided, it will always be used and returned. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001941">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="af762d727316244730b78667d12e26dd6"></a><!-- doxytag: member="utext.h::utext_previous32" ref="af762d727316244730b78667d12e26dd6" args="(UText *ut)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> utext_previous32 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Move the iterator position to the character (code point) whose index precedes the current position, and return that character. </p>
<p>This is a pre-decrement operation.</p>
<p>If the initial position is at the start of the text (index of 0) return U_SENTINEL (-1), and leave the position unchanged.</p>
<p>An inline macro version of this function, <a class="el" href="utext_8h.html#a8aa3d9bae7b252622fe8e70e87758205" title="inline version of utext_previous32(), for performance-critical situations.">UTEXT_PREVIOUS32()</a>, is available for performance critical use.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the previous UChar32 code point, or U_SENTINEL (-1) if the iteration has reached the start of the text. </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="utext_8h.html#a8aa3d9bae7b252622fe8e70e87758205" title="inline version of utext_previous32(), for performance-critical situations.">UTEXT_PREVIOUS32</a> </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001950">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a7d12867d3baae5beeb34351e172b5cd8"></a><!-- doxytag: member="utext.h::utext_previous32From" ref="a7d12867d3baae5beeb34351e172b5cd8" args="(UText *ut, int64_t nativeIndex)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="umachine_8h.html#a09fff5c3b5a5b015324dc3ec3cf92809">UChar32</a> utext_previous32From </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeIndex</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the iteration index, and return the code point preceding the one specified by the initial index. </p>
<p>Leave the iteration position at the start of the returned code point.</p>
<p>This function is the most efficient and convenient way to begin a backwards iteration.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeIndex</em> </td><td>Iteration index in the native units of the text provider. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Code point preceding the one at the initial index, or U_SENTINEL (-1) if it is out of bounds.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001952">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="aa781cea4987dda8a7c5f0351e311bf07"></a><!-- doxytag: member="utext.h::utext_replace" ref="aa781cea4987dda8a7c5f0351e311bf07" args="(UText *ut, int64_t nativeStart, int64_t nativeLimit, const UChar *replacementText, int32_t replacementLength, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t utext_replace </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeStart</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeLimit</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="umachine_8h.html#a6bb9fad572d65b305324ef288165e2ac">UChar</a> * </td>
<td class="paramname"> <em>replacementText</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>replacementLength</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Replace a range of the original text with a replacement text. </p>
<p>Leaves the current iteration position at the position following the newly inserted replacement text.</p>
<p>This function is only available on <a class="el" href="structUText.html" title="UText struct.">UText</a> types that support writing, that is, ones where <a class="el" href="utext_8h.html#af67295033b5dc1b2951b8b05e5ce9222" title="Return TRUE if the text can be written (modified) with utext_replace() or utext_copy()...">utext_isWritable()</a> returns TRUE.</p>
<p>When using this function, there should be only a single <a class="el" href="structUText.html" title="UText struct.">UText</a> opened onto the underlying native text string. Behavior after a replace operation on a <a class="el" href="structUText.html" title="UText struct.">UText</a> is undefined for any other additional UTexts that refer to the modified string.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the <a class="el" href="structUText.html" title="UText struct.">UText</a> representing the text to be operated on. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeStart</em> </td><td>the native index of the start of the region to be replaced </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeLimit</em> </td><td>the native index of the character following the region to be replaced. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>replacementText</em> </td><td>pointer to the replacement text </td></tr>
<tr><td valign="top"></td><td valign="top"><em>replacementLength</em> </td><td>length of the replacement text, or -1 if the text is NUL terminated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>receives any error status. Possible errors include U_NO_WRITE_PERMISSION</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The signed number of (native) storage units by which the length of the text expanded or contracted.</dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001964">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a530b4bb7f0e577008e4930f2b39ecd8a"></a><!-- doxytag: member="utext.h::utext_setNativeIndex" ref="a530b4bb7f0e577008e4930f2b39ecd8a" args="(UText *ut, int64_t nativeIndex)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void utext_setNativeIndex </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t </td>
<td class="paramname"> <em>nativeIndex</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the current iteration position to the nearest code point boundary at or preceding the specified index. </p>
<p>The index is in the native units of the original input text. If the index is out of range, it will be pinned to be within the range of the input text. </p>
<p>It will usually be more efficient to begin an iteration using the functions <a class="el" href="utext_8h.html#a819b23625de643f71280c076feac31a7" title="Set the iteration index and return the code point at that index.">utext_next32From()</a> or <a class="el" href="utext_8h.html#a7d12867d3baae5beeb34351e172b5cd8" title="Set the iteration index, and return the code point preceding the one specified by...">utext_previous32From()</a> rather than setIndex(). </p>
<p>Moving the index position to an adjacent character is best done with <a class="el" href="utext_8h.html#ad4c8e3ba851a3482b2c77cc58cff9ad0" title="Get the code point at the current iteration position of the UText, and advance the...">utext_next32()</a>, <a class="el" href="utext_8h.html#af762d727316244730b78667d12e26dd6" title="Move the iterator position to the character (code point) whose index precedes the...">utext_previous32()</a> or <a class="el" href="utext_8h.html#af91afb68d5059ec704d8d6969288c00d" title="Move the iterator postion by delta code points.">utext_moveIndex32()</a>. Attempting to do direct arithmetic on the index position is complicated by the fact that the size (in native units) of a character depends on the underlying representation of the character (UTF-8, UTF-16, UTF-32, arbitrary codepage), and is not easily knowable.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>the text to be accessed. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>nativeIndex</em> </td><td>the native unit index of the new iteration position. </td></tr>
</table>
</dd>
</dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001954">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
<a class="anchor" id="a024e9470afd51e1ae247dcbfbbbe8a67"></a><!-- doxytag: member="utext.h::utext_setup" ref="a024e9470afd51e1ae247dcbfbbbe8a67" args="(UText *ut, int32_t extraSpace, UErrorCode *status)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structUText.html">UText</a>* utext_setup </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structUText.html">UText</a> * </td>
<td class="paramname"> <em>ut</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"> <em>extraSpace</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="utypes_8h.html#a3343c1c8a8377277046774691c98d78c">UErrorCode</a> * </td>
<td class="paramname"> <em>status</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Common function for use by Text Provider implementations to allocate and/or initialize a new <a class="el" href="structUText.html" title="UText struct.">UText</a> struct. </p>
<p>To be called in the implementation of utext_open() functions. If the supplied <a class="el" href="structUText.html" title="UText struct.">UText</a> parameter is null, a new <a class="el" href="structUText.html" title="UText struct.">UText</a> struct will be allocated on the heap. If the supplied <a class="el" href="structUText.html" title="UText struct.">UText</a> is already open, the provider's close function will be called so that the struct can be reused by the open that is in progress.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ut</em> </td><td>pointer to a <a class="el" href="structUText.html" title="UText struct.">UText</a> struct to be re-used, or null if a new <a class="el" href="structUText.html" title="UText struct.">UText</a> should be allocated. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>extraSpace</em> </td><td>The amount of additional space to be allocated as part of this <a class="el" href="structUText.html" title="UText struct.">UText</a>, for use by types of providers that require additional storage. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>Errors are returned here. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>pointer to the <a class="el" href="structUText.html" title="UText struct.">UText</a>, allocated if necessary, with extra space set up if requested. </dd></dl>
<dl class="stable"><dt><b><a class="el" href="stable.html#_stable001979">Stable:</a></b></dt><dd>ICU 3.4 </dd></dl>
</div>
</div>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 16 Mar 2010 for ICU 4.4 by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
distrib
>
Mandriva
>
current
>
i586
>
media
>
main-updates
>
by-pkgid
>
f51238514e2abe817779ad2fe01b0759
>
files
>
783
