From kido@vnet.ibm.com Wed Oct  7 07:44:04 1992
Received: from vnet.ibm.com by dkuug.dk via EUnet with SMTP (5.64+/8+bit/IDA-1.2.8)
	id AA20874; Wed, 7 Oct 92 07:44:04 +0100
Message-Id: <9210070644.AA20874@dkuug.dk>
Received: from YMTVM8 by vnet.ibm.com (IBM VM SMTP V2R2) with BSMTP id 5012;
   Wed, 07 Oct 92 02:46:32 EDT
Date: Wed, 7 Oct 92 15:43:33 JST
From: "Akio    Kido" <kido@vnet.ibm.com>
To: sc22wg15@dkuug.dk
Subject: mse.trf.7
X-Charset: ASCII
X-Char-Esc: 29

#! /bin/sh
#
# This is shell archive.
# Remove anything before this line, then unpack this
# file by saveing it into a $file and typing
# "sh $file".
#
# Contents:
#	-rw-rw-rw- string.mm
#	-rw-rw-rw- time.mm
#
sed "s/^X//" > string.mm << 'EOF'
X'\".pH "WIDE STRING HANDLING FUNCTIONS"
X.H 2 "Wide string handling"
X.P
XSeveral functions for manipulating wide strings
X(that is, array of \*(WC) are declared in the header file
X.Cf <wchar.h>.
XVarious methods are used for determining the lengths of
Xarrays, but in all cases a \*(Cwwchar_t *\fP or \*(Cwvoid *\fP
Xargument always points to the initial (lowest addressed)
Xwide character of the array.
XIf an array is accessed beyond the end of an object,
Xthe behavior is undefined.
X.H 3 "Wide string copy functions"
X.H 4 "The \f(CBwcscpy\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcscpy(wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcscpy
Xfunction copies the wide string pointed to by
X.Cf s2
X(including the terminating null wide  character) into the wide character array
Xpointed to by
X.Cf s1 .
XIf copying takes place between objects that overlap,
Xthe behavior is undefined.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcscpy
Xfunction returns the value of
X.Cf s1 .
X
X.H 4 "The \f(CBwcsncpy\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcsncpy(wchar_t *s1, const wchar_t *s2, size_t n);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsncpy
Xfunction copies not more than
X.Cf n
Xwide characters
X(wide characters that follow a null wide character are not
Xcopied)
Xfrom the wide character array pointed to by
X.Cf s2
Xto the wide character array pointed to by
X.Cf s1 .
XIf copying takes place between objects that overlap,
Xthe behavior is undefined.
X.P
XIf the wide character array pointed to by
X.Cf s2
Xis a wide string that is shorter than
X.Cf n
Xwide characters,
Xnull wide characters are appended
Xto the copy in the wide character array pointed to by
X.Cf s1 ,
Xuntil
X.Cf n
Xwide characters in all have been written.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcsncpy
Xfunction returns the value of
X.Cf s1 .
X
X.H 4 "The \f(CBwcscat\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcscat(wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcscat
Xfunction appends a copy of the wide string pointed to by
X.Cf s2
X(including the terminating null wide character) to the end of the
Xwide string pointed to by
X.Cf s1 .
XThe initial wide character of
X.Cf s2
Xoverwrites the null wide character at the end of
X.Cf s1 .
XIf copying takes place between objects that overlap,
Xthe behavior is undefined.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcscat
Xfunction returns the value of
X.Cf s1 .
X
X.H 4 "The \f(CBwcsncat\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcsncat(wchar_t *s1, const wchar_t *s2, size_t n);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsncat
Xfunction appends not more than
X.Cf n
Xwide characters
X(a null wide character and wide characters that follow it are not appended)
Xfrom the wide character array pointed to by
X.Cf s2
Xto the end of the wide string pointed to by
X.Cf s1 .
XThe initial wide character of
X.Cf s2
Xoverwrites the null wide character at the end of
X.Cf s1 .
XA terminating null wide character is always appended to the result.
XIf copying takes place between objects that overlap,
Xthe behavior is undefined.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcsncat
Xfunction returns the value of
X.Cf s1 .
X
X.H 3 "Wide string comparison functions"
X.H 4 "The \f(CBwcscoll\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	int wcscoll(const wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcscoll
Xfunction compares the wide string pointed to by \*(Cws1\fP
Xto the wide string pointed to by \*(Cws2\fP,
Xboth interpreted as appropriate to the
X.Cf LC_COLLATE
Xcategory of the current locale.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcscoll
Xfunction returns an integer greater than, equal to, or less than zero,
Xaccording as the wide string pointed to by \*(Cws1\fP is greater than,
Xequal to, or less than the wide string pointed to by \*(Cws2\fP when
Xboth are interpreted as appropriate to the current locale.
X.br
X
X.H 4 "The \f(CBwcscmp\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	int wcscmp(const wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcscmp
Xfunction compares the wide string pointed to by
X.Cf s1
Xto the wide string pointed to by
X.Cf s2 .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcscmp
Xfunction returns an integer greater than, equal to, or less than zero,
Xaccording as the wide string pointed to by
X.Cf s1
Xis greater than, equal to, or less than the wide string
Xpointed to by
X.Cf s2 .
X
X.H 4 "The \f(CBwcsncmp\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsncmp
Xfunction compares not more than
X.Cf n
Xwide characters
X(wide characters that follow a null wide character are not compared)
Xfrom the wide character array pointed to by
X.Cf s1
Xto the wide character array pointed to by
X.Cf s2 .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcsncmp
Xfunction returns an integer greater than, equal to, or less than zero,
Xaccording as the possibly null-terminated wide character array pointed to by
X.Cf s1
Xis greater than, equal to, or less than the possibly null-terminated
Xwide character array pointed to by
X.Cf s2 .
X
X.br
X.H 4 "The \f(CBwcsxfrm\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	size_t wcsxfrm(wchar_t *s1, const wchar_t *s2, size_t n);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsxfrm
Xfunction transforms the wide string pointed to by \*(Cws2\fP and places the
Xresulting wide string into the array pointed to by \*(Cws1\fP.
XThe transformation is such that if the
X.Cf wcscmp
Xfunction is applied to two transformed wide strings, it returns a value
Xgreater than, equal to, or less than zero, corresponding to the result of the
X.Cf wcscoll
Xfunction applied to the same two original wide strings.
XNo more than \*(Cwn\fP wide characters are placed into the resulting array poin
Xto by \*(Cws1\fP, including the terminating null wide character.  If \*(Cwn\fP
Xzero, \*(Cws1\fP is permitted to be a null wide pointer.  If copying takes
Xplace between objects that overlap, the behavior is undefined.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcsxfrm
Xfunction returns the length of the transformed wide string
X(not including the terminating null wide character).
XIf the value returned is \*(Cwn\fP or more,
Xthe contents of the array pointed to by \*(Cws1\fP are indeterminate.
X.br
X
X.H 3 "Wide string search functions"
X.H 4 "The \f(CBwcschr\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcschr(const wchar_t *s, wint_t c);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcschr
Xfunction locates the first occurrence of
X.Cf c
X.mc |
Xin the wide string pointed to by
X.mc
X.Cf s .
XThe terminating null wide character is considered to be part of the wide string
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcschr
Xfunction returns a pointer to the located wide character,
Xor a null pointer if the wide character does not occur in the wide string.
X
X.H 4 "The \f(CBwcscspn\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcscspn
Xfunction computes the length of the maximum initial segment of the wide
Xstring pointed to by
X.Cf s1
Xwhich consists entirely of wide characters \f2not\fP from the wide string
Xpointed to by
X.Cf s2 .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcscspn
Xfunction returns the length of the segment.
X
X.H 4 "The \f(CBwcspbrk\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcspbrk
Xfunction locates the first occurrence in the wide string pointed to by
X.Cf s1
Xof any wide character from the wide string pointed to by
X.Cf s2 .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcspbrk
Xfunction returns a pointer to the wide character, or a null pointer
Xif no wide character from the wide string from
X.Cf s2
Xoccurs in
X.Cf s1 .
X
X.H 4 "The \f(CBwcsrchr\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	wchar_t *wcsrchr(const wchar_t *s, wint_t c);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsrchr
Xfunction locates the last occurrence of
X.Cf c
X.mc |
Xin the wide string pointed to by
X.mc
X.Cf s .
XThe terminating null wide character is considered to be part of the wide string
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcsrchr
Xfunction returns a pointer to the wide character, or a null pointer if
X.Cf c
Xdoes not occur in the wide string.
X
X.H 4 "The \f(CBwcsspn\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsspn
Xfunction computes the length of the maximum initial segment of the
Xwide string
Xpointed to by
X.Cf s1
Xwhich consists entirely of wide characters from the wide
Xstring pointed to by
X.Cf s2 .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcsspn
Xfunction returns the length of the segment.
X
X.mc |
X.H 4 "The \f(CBwcsstr\fP function"
X.mc
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X.mc |
X	wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
X.mc
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.mc |
X.Cf wcsstr
X.mc
Xfunction locates the first occurrence in the wide string pointed to by
X.Cf s1
Xof the sequence of wide characters
X(excluding the terminating null wide character)
Xin the wide string pointed to by
X.Cf s2 .
X.HU "Returns"
X.br
X.P
XThe
X.mc |
X.Cf wcsstr
X.mc
Xfunction returns a pointer to the located wide string,
Xor a null pointer if the wide string is not found.
XIf
X.Cf s2
Xpoints to a wide string with zero length,
Xthe function returns
X.Cf s1 .
X
X.H 4 "The \f(CBwcstok\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X.mc |
X	wchar_t *wcstok(wchar_t *s1, const wchar_t *s2, wchar_t **ptr);
X.mc
X.Ce
X.HU "Description"
X.br
X.P
X.mc |
XA sequence of calls to the
X.mc
X.Cf wcstok
X.mc |
Xfunction breaks the wide string pointed to
Xby
X.mc
X.Cf s1
X.mc |
Xinto a sequence of tokens, each of which is delimited by a wide character
Xfrom the wide string pointed to by
X.Cf s2.
XThe third argument points to a caller-provided
X.Cf wchar_t
Xpointer into which the
X.Cf wcstok
Xfunction stores information
Xnecessary for it to continue scanning the same string.
X.P
XFor the first call in the sequence,
X.mc
X.Cf s1
X.mc |
Xshall point to a wide string, while
Xin subsequent calls for the same wide string,
X.Cf s1
Xshall be null pointer.  If
X.Cf s1
Xis a null pointer, the value pointed to by
X.Cf ptr
Xshall match that set by the
Xprevious call for the same wide string; otherwise its value is ignored.  The
Xseparator wide string pointed to by
X.mc
X.Cf s2
Xmay be different from call to call.
X.P
X.mc |
XThe first call in the sequence searches the wide string pointed to by
X.Cf s1
Xfor
Xthe first wide character that is not contained in the current separator wide
Xstring pointed to by
X.Cf s2.
XIf no such wide character is found, then there are
Xno tokens in the string pointed to by \*(Cws1\fP and the wcstok function return
Xpointer.  If such a wide character is found, it is the start of the first token
X.mc
X.P
XThe
X.Cf wcstok
X.mc |
Xfunction then searches from there for a wide character that is
Xcontained in the current separator wide string.  If no such wide character is
Xfound, the current token extends to the end of the wide string pointed to by
X.Cf s1,
Xand subsequent searches in the same wide string for a token will return a null
Xpointer.  If such a wide character is found, it is overwritten with by a null
Xwide character, which terminates the current token.
X.mc
X.P
X.mc |
XIn all cases, the
X.Cf wcstok
Xfunction stores sufficient information in the
Xpointer pointed to by
X.Cf ptr
Xso that subsequent calls, with a null pointer as the
Xvalue the first argument and the unmodified pointer value as the third, will
Xstart searching just past the end of the previously returned token (if any).
X.mc
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcstok
X.mc |
Xfunction returns a pointer to the first wide character of a
Xtoken, or a null pointer if there is no token.
X.mc
X
X.mc |
X.HU "Example"
X.Cb
X   #include <wchar.h>
X   static wchar_t str1[] = L"?a??b,,,#c";
X   static wchar_t str2[] = L"\et \et";
X   wchar_t *t, *ptr1, *ptr2;
X
X   t = wcstok(str1, L"?", &ptr1);   /* t points to the token L"a" */
X   t = wcstok(NULL, L",", &ptr1);   /* t points to the token L"??b" */
X   t = wcstok(str2, L" \et", &ptr2); /* t is a null pointer */
X   t = wcstok(NULL, L"#,", &ptr1);  /* t points to the token L"c" */
X   t = wcstok(NULL, L"?", &ptr1);   /* t is a null pointer */
X.Ce
X
X.mc
X.H 4 "The \f(CBwcslen\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	size_t wcslen(const wchar_t *s);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcslen
Xfunction computes the length of the wide string pointed to by
X.Cf s .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcslen
Xfunction returns the number of wide characters that precede the
Xterminating null wide character,
X
X.H 3 "Printing position functions"
X.H 4 "The \f(CBwcswidth\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	int wcswidth(const wchar_t *s, size_t n);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcswidth
Xfunction determines the number of printing positions that
Xa graphic representation of \*(Cwn\fP wide characters (or fewer than \*(Cwn\fP
Xcharacters if a null wide character is encountered before \*(Cwn\fP wide charac
Xhave been exhausted) in the wide string pointed to by \*(Cws\fP
Xoccupies on a display device. Each of printing wide characters occupies
Xits own number of printing positions on a display device. The number is
Xindependent of its location on the device.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcswidth
Xfunction either returns
X.Cf 0
X(if \*(Cws\fP points to a null wide
Xcharacter), or returns the number of printing positions occupied by
Xthe wide string pointed to by \*(Cws\fP, or returns
X.Cf \-1
X(if any wide character in the wide string pointed to by \*(Cws\fP is not
Xa printing wide character).
X
X.H 4 "The \f(CBwcwidth\fP function"
X.HU "Synopsis"
X'\"	#include <string.h>
X.Cb
X	#include <wchar.h>
X	int wcwidth(wint_t c);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcwidth
Xfunction determines the number of printing positions that
X.mc |
Xa graphic representation of \*(Cwc\fP occupies
X.mc
Xon a display device. Each of printing wide characters occupies
Xits own number of printing positions on a display device. The number is
Xindependent of its location on the device.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wcwidth
Xfunction either returns
X.Cf 0
X(if \*(Cwc\fP is a null wide character),
Xor returns the number of printing positions occupied by
X.mc |
X\*(Cwc\fP, or returns
X.mc
X.Cf \-1
X(if \*(Cwc\fP is not a printing
Xwide character).
X.br
EOF
chmod 666 string.mm
sed "s/^X//" > time.mm << 'EOF'
X'\".pH "DATE AND TIME"
X.H 2 "Date and time"
X.H 3 "Wide string time conversion functions"
X.H 4 "The \f(CBwcsftime\fP function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	size_t wcsftime(wchar_t *s, size_t maxsize,
X		const wchar_t *format, const struct tm *timeptr);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wcsftime
Xfunction is equivalent to
X.Cf strftime
X.mc |
Xfunction, except that:
X.BL
X.LI
XThe argument \*(Cws\fP specifies an array
Xof a wide string into which the generated output is to be placed.
X.LI
XThe argument
X.Cf maxsize
Xindicates a number of wide characters.
X.LI
XThe argument
X.Cf format
Xspecifies an array of wide characters comprising the format
Xstring.
X.LI
XThe return value indicates a number of wide characters.
X.LE
X
X.mc
X.HU "Returns"
X.br
X.P
XIf the total number of resulting wide characters including the terminating
Xnull wide character is not more than \*(Cwmaxsize\fP, the
X.Cf wcsftime
Xfunction returns the number of wide characters placed into the
Xarray pointed to by \*(Cws\fP not including the
Xterminating null wide character. Otherwise, zero is returned
Xand the contents of the array are indeterminate.
X.br
X.mc *
X.mc
EOF
chmod 666 time.mm