[apple/libc.git] / locale / mbrune.3

.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Paul Borman at Krystal Technologies.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mbrune.3	8.2 (Berkeley) 4/19/94
.\" $FreeBSD: src/lib/libc/locale/mbrune.3,v 1.15 2003/02/06 11:04:46 charnier Exp $
.\"
.Dd April 19, 1994
.Dt MBRUNE 3
.Os
.Sh NAME
.Nm mbrune ,
.Nm mbrrune ,
.Nm mbmb
.Nd multibyte rune support for C
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rune.h
.Ft char *
.Fn mbrune "const char *string" "rune_t rune"
.Ft char *
.Fn mbrrune "const char *string" "rune_t rune"
.Ft char *
.Fn mbmb "const char *string" "char *pattern"
.Sh DESCRIPTION
.Bf Em
The
.Bx 4.4
.Dq rune
functions have been deprecated in favour of the
.Tn ISO
C99 extended multibyte and wide character facilities
and should not be used in new applications.
.Ef
Consider working with wide characters instead, and using
.Xr wcschr 3 ,
.Xr wcsrchr 3 ,
and
.Xr wcsstr 3
instead of these functions.
.Pp
These routines provide the corresponding functionality of
.Fn strchr ,
.Fn strrchr
and
.Fn strstr
for multibyte strings.
.Pp
The
.Fn mbrune
function locates the first occurrence of
.Fn rune
in the string pointed to by
.Fa string .
The terminating
.Dv NUL
character is considered part of the string.
If
.Fa rune
is
.Ql \e0 ,
.Fn mbrune
locates the terminating
.Ql \e0 .
.Pp
The
.Fn mbrrune
function
locates the last occurrence of
.Fa rune
in the string
.Fa string .
If
.Fa rune
is
.Ql \e0 ,
.Fn mbrune
locates the terminating
.Ql \e0 .
.Pp
The
.Fn mbmb
function locates the first occurrence of the null-terminated string
.Fa pattern
in the null-terminated string
.Fa string .
If
.Fa pattern
is the empty string,
.Fn mbmb
returns
.Fa string ;
if
.Fa pattern
occurs nowhere in
.Fa string ,
.Fn mbmb
returns
.Dv NULL ;
otherwise
.Fn mbmb
returns a pointer to the first character of the first occurrence of
.Fa pattern .
.Sh RETURN VALUES
The function
.Fn mbrune
returns a pointer to the located character, or
.Dv NULL
if the character does not appear in the string.
.Pp
The
.Fn mbrrune
function
returns a pointer to the character, or
.Dv NULL
if the character does not appear in the string.
.Pp
The
.Fn mbmb
function
returns a pointer to the
.Fa pattern ,
or
.Dv NULL
if the
.Fa pattern
does not appear in the string.
.Sh SEE ALSO
.Xr rune 3 ,
.Xr setlocale 3 ,
.Xr euc 4 ,
.Xr utf2 4 ,
.Xr utf8 5
.Sh HISTORY
The
.Fn mbrune ,
.Fn mbrrune ,
and
.Fn mbmb
functions
first appeared in Plan 9 from Bell Labs as
.Fn utfrune ,
.Fn utfrrune ,
and
.Fn utfutf .
Commit	Line	Data
5b2abdfb A	1	.\" Copyright (c) 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Paul Borman at Krystal Technologies.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
	35	.\" @(#)mbrune.3 8.2 (Berkeley) 4/19/94
9385eb3d	36	.\" $FreeBSD: src/lib/libc/locale/mbrune.3,v 1.15 2003/02/06 11:04:46 charnier Exp $
5b2abdfb A	37	.\"
	38	.Dd April 19, 1994
	39	.Dt MBRUNE 3
	40	.Os
	41	.Sh NAME
	42	.Nm mbrune ,
	43	.Nm mbrrune ,
	44	.Nm mbmb
	45	.Nd multibyte rune support for C
	46	.Sh LIBRARY
	47	.Lb libc
	48	.Sh SYNOPSIS
	49	.In rune.h
	50	.Ft char *
	51	.Fn mbrune "const char *string" "rune_t rune"
	52	.Ft char *
	53	.Fn mbrrune "const char *string" "rune_t rune"
	54	.Ft char *
	55	.Fn mbmb "const char string" "char pattern"
	56	.Sh DESCRIPTION
9385eb3d A	57	.Bf Em
	58	The
	59	.Bx 4.4
	60	.Dq rune
	61	functions have been deprecated in favour of the
	62	.Tn ISO
	63	C99 extended multibyte and wide character facilities
	64	and should not be used in new applications.
	65	.Ef
	66	Consider working with wide characters instead, and using
	67	.Xr wcschr 3 ,
	68	.Xr wcsrchr 3 ,
	69	and
	70	.Xr wcsstr 3
	71	instead of these functions.
	72	.Pp
5b2abdfb A	73	These routines provide the corresponding functionality of
	74	.Fn strchr ,
	75	.Fn strrchr
	76	and
	77	.Fn strstr
	78	for multibyte strings.
	79	.Pp
	80	The
	81	.Fn mbrune
	82	function locates the first occurrence of
	83	.Fn rune
	84	in the string pointed to by
9385eb3d	85	.Fa string .
5b2abdfb A	86	The terminating
	87	.Dv NUL
	88	character is considered part of the string.
	89	If
	90	.Fa rune
	91	is
	92	.Ql \e0 ,
	93	.Fn mbrune
	94	locates the terminating
	95	.Ql \e0 .
	96	.Pp
	97	The
	98	.Fn mbrrune
	99	function
	100	locates the last occurrence of
	101	.Fa rune
	102	in the string
	103	.Fa string .
	104	If
	105	.Fa rune
	106	is
	107	.Ql \e0 ,
	108	.Fn mbrune
	109	locates the terminating
	110	.Ql \e0 .
	111	.Pp
	112	The
	113	.Fn mbmb
	114	function locates the first occurrence of the null-terminated string
	115	.Fa pattern
	116	in the null-terminated string
	117	.Fa string .
	118	If
	119	.Fa pattern
	120	is the empty string,
	121	.Fn mbmb
	122	returns
	123	.Fa string ;
	124	if
	125	.Fa pattern
	126	occurs nowhere in
	127	.Fa string ,
	128	.Fn mbmb
	129	returns
	130	.Dv NULL ;
	131	otherwise
	132	.Fn mbmb
	133	returns a pointer to the first character of the first occurrence of
	134	.Fa pattern .
	135	.Sh RETURN VALUES
	136	The function
	137	.Fn mbrune
	138	returns a pointer to the located character, or
	139	.Dv NULL
	140	if the character does not appear in the string.
	141	.Pp
	142	The
	143	.Fn mbrrune
	144	function
	145	returns a pointer to the character, or
	146	.Dv NULL
	147	if the character does not appear in the string.
	148	.Pp
	149	The
150	.Fn mbmb
151	function
152	returns a pointer to the
153	.Fa pattern ,
154	or
155	.Dv NULL
156	if the
157	.Fa pattern
158	does not appear in the string.
9385eb3d	159	.Sh SEE ALSO
5b2abdfb A	160	.Xr rune 3 ,
	161	.Xr setlocale 3 ,
	162	.Xr euc 4 ,
9385eb3d A	163	.Xr utf2 4 ,
9385eb3d A	164	.Xr utf8 5
5b2abdfb A	165	.Sh HISTORY
	166	The
	167	.Fn mbrune ,
	168	.Fn mbrrune ,
	169	and
	170	.Fn mbmb
	171	functions
	172	first appeared in Plan 9 from Bell Labs as
	173	.Fn utfrune ,
	174	.Fn utfrrune ,
	175	and
	176	.Fn utfutf .