Blame - rune.3 - platform/external/libutf

blob: 0e38eb3d75561d99f94317ae9f18c3b19095283e [file] [log] [blame]

Alexander Gutkin	439f3d1	2014-02-28 11:33:45 +0000	[diff] [blame]	1	.deEX
				2	.ift .ft5
				3	.nf
				4	..
				5	.deEE
				6	.ft1
				7	.fi
				8	..
				9	.TH RUNE 3
				10	.SH NAME
				11	runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf \- rune/UTF conversion
				12	.SH SYNOPSIS
				13	.ta \w'\fLchar*xx'u
				14	.B #include <utf.h>
				15	.PP
				16	.B
				17	int runetochar(char s, Rune r)
				18	.PP
				19	.B
				20	int chartorune(Rune r, char s)
				21	.PP
				22	.B
				23	int runelen(long r)
				24	.PP
				25	.B
				26	int runenlen(Rune *r, int n)
				27	.PP
				28	.B
				29	int fullrune(char *s, int n)
				30	.PP
				31	.B
				32	char* utfecpy(char s1, char es1, char *s2)
				33	.PP
				34	.B
				35	int utflen(char *s)
				36	.PP
				37	.B
				38	int utfnlen(char *s, long n)
				39	.PP
				40	.B
				41	char* utfrune(char *s, long c)
				42	.PP
				43	.B
				44	char* utfrrune(char *s, long c)
				45	.PP
				46	.B
				47	char* utfutf(char s1, char s2)
				48	.SH DESCRIPTION
				49	These routines convert to and from a
				50	.SM UTF
				51	byte stream and runes.
				52	.PP
				53	.I Runetochar
				54	copies one rune at
				55	.I r
				56	to at most
				57	.B UTFmax
				58	bytes starting at
				59	.I s
				60	and returns the number of bytes copied.
				61	.BR UTFmax ,
				62	defined as
				63	.B 3
				64	in
				65	.BR <libc.h> ,
				66	is the maximum number of bytes required to represent a rune.
				67	.PP
				68	.I Chartorune
				69	copies at most
				70	.B UTFmax
				71	bytes starting at
				72	.I s
				73	to one rune at
				74	.I r
				75	and returns the number of bytes copied.
				76	If the input is not exactly in
				77	.SM UTF
				78	format,
				79	.I chartorune
				80	will convert to 0x80 and return 1.
				81	.PP
				82	.I Runelen
				83	returns the number of bytes
				84	required to convert
				85	.I r
				86	into
				87	.SM UTF.
				88	.PP
				89	.I Runenlen
				90	returns the number of bytes
				91	required to convert the
				92	.I n
				93	runes pointed to by
				94	.I r
				95	into
				96	.SM UTF.
				97	.PP
				98	.I Fullrune
				99	returns 1 if the string
				100	.I s
				101	of length
				102	.I n
				103	is long enough to be decoded by
				104	.I chartorune
				105	and 0 otherwise.
				106	This does not guarantee that the string
				107	contains a legal
				108	.SM UTF
				109	encoding.
				110	This routine is used by programs that
				111	obtain input a byte at
				112	a time and need to know when a full rune
				113	has arrived.
				114	.PP
				115	The following routines are analogous to the
				116	corresponding string routines with
				117	.B utf
				118	substituted for
				119	.B str
				120	and
				121	.B rune
				122	substituted for
				123	.BR chr .
				124	.PP
				125	.I Utfecpy
				126	copies UTF sequences until a null sequence has been copied, but writes no
				127	sequences beyond
				128	.IR es1 .
				129	If any sequences are copied,
				130	.I s1
				131	is terminated by a null sequence, and a pointer to that sequence is returned.
				132	Otherwise, the original
				133	.I s1
				134	is returned.
				135	.PP
				136	.I Utflen
				137	returns the number of runes that
				138	are represented by the
				139	.SM UTF
				140	string
				141	.IR s .
				142	.PP
				143	.I Utfnlen
				144	returns the number of complete runes that
				145	are represented by the first
				146	.I n
				147	bytes of
				148	.SM UTF
				149	string
				150	.IR s .
				151	If the last few bytes of the string contain an incompletely coded rune,
				152	.I utfnlen
				153	will not count them; in this way, it differs from
				154	.IR utflen ,
				155	which includes every byte of the string.
				156	.PP
				157	.I Utfrune
				158	.RI ( utfrrune )
				159	returns a pointer to the first (last)
				160	occurrence of rune
				161	.I c
				162	in the
				163	.SM UTF
				164	string
				165	.IR s ,
				166	or 0 if
				167	.I c
				168	does not occur in the string.
				169	The NUL byte terminating a string is considered to
				170	be part of the string
				171	.IR s .
				172	.PP
				173	.I Utfutf
				174	returns a pointer to the first occurrence of
				175	the
				176	.SM UTF
				177	string
				178	.I s2
				179	as a
				180	.SM UTF
				181	substring of
				182	.IR s1 ,
				183	or 0 if there is none.
				184	If
				185	.I s2
				186	is the null string,
				187	.I utfutf
				188	returns
				189	.IR s1 .
				190	.SH SOURCE
				191	.B http://swtch.com/plan9port/unix
				192	.SH SEE ALSO
				193	.IR utf (7),
				194	.IR tcs (1)