Google Git
Sign in
plan9port / plan9 / 78e51a8c6678b6e3dff3d619aa786669f531f4bc / . / man / man3 / rune.html
blob: 2fed11f3efe825a2405448a9cd56ee211f09f994 [file] [log] [blame]
<head>
<title>rune(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>RUNE(3)</b><td align=right><b>RUNE(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
runetochar, chartorune, runelen, runenlen, fullrune, utfecpy,
utflen, utfnlen, utfrune, utfrrune, utfutf &ndash; rune/UTF conversion<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include &lt;u.h&gt;<br>
#include &lt;libc.h&gt;
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;runetochar(char *s, Rune *r)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;chartorune(Rune *r, char *s)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;runelen(long r)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;runenlen(Rune *r, int n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fullrune(char *s, int n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>char* &nbsp;&nbsp;&nbsp;utfecpy(char *s1, char *es1, char *s2)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;utflen(char *s)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;utfnlen(char *s, long n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>char* &nbsp;&nbsp;&nbsp;utfrune(char *s, long c)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>char* &nbsp;&nbsp;&nbsp;utfrrune(char *s, long c)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>char* &nbsp;&nbsp;&nbsp;utfutf(char *s1, char *s2)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
These routines convert to and from a UTF byte stream and runes.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Runetochar</i> copies one rune at <i>r</i> to at most <tt><font size=+1>UTFmax</font></tt> bytes starting
at <i>s</i> and returns the number of bytes copied. <tt><font size=+1>UTFmax</font></tt>, defined as
<tt><font size=+1>3</font></tt> in <tt><font size=+1>&lt;libc.h&gt;</font></tt>, is the maximum number of bytes required to represent
a rune.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Chartorune</i> copies at most <tt><font size=+1>UTFmax</font></tt> bytes starting at <i>s</i> to one rune
at <i>r</i> and returns the number of bytes copied. If the input is not
exactly in UTF format, <i>chartorune</i> will convert to 0x80 and return
1.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Runelen</i> returns the number of bytes required to convert <i>r</i> into
UTF.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Runenlen</i> returns the number of bytes required to convert the <i>n</i>
runes pointed to by <i>r</i> into UTF.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fullrune</i> returns 1 if the string <i>s</i> of length <i>n</i> is long enough
to be decoded by <i>chartorune</i> and 0 otherwise. This does not guarantee
that the string contains a legal UTF encoding. This routine is
used by programs that obtain input a byte at a time and need to
know when a full rune has arrived.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The following routines are analogous to the corresponding string
routines with <tt><font size=+1>utf</font></tt> substituted for <tt><font size=+1>str</font></tt> and <tt><font size=+1>rune</font></tt> substituted for
<tt><font size=+1>chr</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Utfecpy</i> copies UTF sequences until a null sequence has been copied,
but writes no sequences beyond <i>es1</i>. If any sequences are copied,
<i>s1</i> is terminated by a null sequence, and a pointer to that sequence
is returned. Otherwise, the original <i>s1</i> is returned.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Utflen</i> returns the number of runes that are represented by the
UTF string <i>s</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Utfnlen</i> returns the number of complete runes that are represented
by the first <i>n</i> bytes of UTF string <i>s</i>. If the last few bytes of
the string contain an incompletely coded rune, <i>utfnlen</i> will not
count them; in this way, it differs from <i>utflen</i>, which includes
every byte of the string.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Utfrune</i> (<i>utfrrune</i>) returns a pointer to the first (last) occurrence
of rune <i>c</i> in the UTF string <i>s</i>, or 0 if <i>c</i> does not occur in the
string. The NUL byte terminating a string is considered to be
part of the string <i>s</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Utfutf</i> returns a pointer to the first occurrence of the UTF string
<i>s2</i> as a UTF substring of <i>s1</i>, or 0 if there is none. If <i>s2</i> is the
null string, <i>utfutf</i> returns <i>s1</i>.<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/lib9/utf/rune.c<br>
/usr/local/plan9/src/lib9/utf/utfrune.c<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man7/utf.html"><i>utf</i>(7)</a>, <a href="../man1/tcs.html"><i>tcs</i>(1)</a><br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>