[unix-history] / lib / libc / 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.1 (Berkeley) 6/4/93
.\"
.Dd "June 4, 1993"
.Dt MBRUNE 3
.Os
.Sh NAME
.Nm mbrune ,
.Nm mbrrune ,
.Nm mbmb
.Nd multibyte rune support for C
.Sh SYNOPSIS
.Fd #include <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
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
.Ar string .
The terminating
.Dv NULL
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 euc 4 ,
.Xr mbrune 3 ,
.Xr rune 3 ,
.Xr setlocale 3 ,
.Xr utf2 4
.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
a5db3a15 GW	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.1 (Berkeley) 6/4/93
	36	.\"
	37	.Dd "June 4, 1993"
	38	.Dt MBRUNE 3
	39	.Os
	40	.Sh NAME
	41	.Nm mbrune ,
	42	.Nm mbrrune ,
	43	.Nm mbmb
	44	.Nd multibyte rune support for C
	45	.Sh SYNOPSIS
	46	.Fd #include <rune.h>
	47	.Ft char *
	48	.Fn mbrune "const char *string" "rune_t rune"
	49	.Ft char *
	50	.Fn mbrrune "const char *string" "rune_t rune"
	51	.Ft char *
	52	.Fn mbmb "const char string" "char pattern"
	53	.Sh DESCRIPTION
	54	These routines provide the corresponding functionality of
	55	.Fn strchr ,
	56	.Fn strrchr
	57	and
	58	.Fn strstr
	59	for multibyte strings.
	60	.Pp
	61	The
	62	.Fn mbrune
8f8a9528	63	function locates the first occurrence of
a5db3a15 GW	64	.Fn rune
	65	in the string pointed to by
	66	.Ar string .
	67	The terminating
	68	.Dv NULL
	69	character is considered part of the string.
	70	If
	71	.Fa rune
	72	is
	73	.Ql \e0 ,
	74	.Fn mbrune
	75	locates the terminating
	76	.Ql \e0 .
	77	.Pp
	78	The
	79	.Fn mbrrune
	80	function
	81	locates the last occurrence of
	82	.Fa rune
	83	in the string
	84	.Fa string .
	85	If
	86	.Fa rune
	87	is
	88	.Ql \e0 ,
	89	.Fn mbrune
	90	locates the terminating
	91	.Ql \e0 .
	92	.Pp
	93	The
	94	.Fn mbmb
8f8a9528	95	function locates the first occurrence of the null-terminated string
a5db3a15 GW	96	.Fa pattern
	97	in the null-terminated string
	98	.Fa string.
	99	If
	100	.Fa pattern
	101	is the empty string,
	102	.Fn mbmb
	103	returns
	104	.Fa string ;
	105	if
	106	.Fa pattern
	107	occurs nowhere in
	108	.Fa string ,
	109	.Fn mbmb
	110	returns
	111	.Dv NULL ;
	112	otherwise
	113	.Fn mbmb
	114	returns a pointer to the first character of the first occurrence of
	115	.Fa pattern .
	116	.Sh RETURN VALUES
	117	The function
	118	.Fn mbrune
	119	returns a pointer to the located character, or
	120	.Dv NULL
	121	if the character does not appear in the string.
	122	.Pp
	123	The
	124	.Fn mbrrune
	125	function
	126	returns a pointer to the character, or
	127	.Dv NULL
	128	if the character does not appear in the string.
	129	.Pp
	130	The
	131	.Fn mbmb
	132	function
	133	returns a pointer to the
	134	.Fa pattern ,
	135	or
	136	.Dv NULL
	137	if the
	138	.Fa pattern
	139	does not appear in the string.
	140	.Sh "SEE ALSO
	141	.Xr euc 4 ,
	142	.Xr mbrune 3 ,
	143	.Xr rune 3 ,
	144	.Xr setlocale 3 ,
	145	.Xr utf2 4
	146	.Sh HISTORY
	147	The
	148	.Fn mbrune ,
	149	.Fn mbrrune ,
	150	and
	151	.Fn mbmb
	152	functions
	153	first appeared in Plan 9 from Bell Labs as
	154	.Fn utfrune ,
	155	.Fn utfrrune ,
	156	and
	157	.Fn utfutf .