--- str.3 2000/07/14 15:24:16 1.32
+++ str.3 2001/04/27 12:22:21 1.33
@@ -1,9 +1,9 @@
-.rn '' }`
-''' $RCSfile$$Revision$$Date$
-'''
-''' $Log$
-'''
-.de Sh
+.\" Automatically generated by Pod::Man version 1.02
+.\" Sun Dec 31 12:23:40 2000
+.\"
+.\" Standard preamble:
+.\" ======================================================================
+.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
@@ -11,150 +11,106 @@
\fB\\$1\fR
.PP
..
-.de Sp
+.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
-.de Ip
+.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
-.de Vb
+.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
-.de Ve
+.de Ve \" End verbatim text
.ft R
.fi
..
-'''
-'''
-''' Set up \*(-- to give an unbreakable dash;
-''' string Tr holds user defined translation string.
-''' Bell System Logo is used as a dummy character.
-'''
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
+.\" to do unbreakable dashes and therefore won't be available. \*(C` and
+.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
-.ds -- \(*W-
-.ds PI pi
-.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-.ds L" ""
-.ds R" ""
-''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
-''' \*(L" and \*(R", except that they are used on ".xx" lines,
-''' such as .IP and .SH, which do another additional levels of
-''' double-quote interpretation
-.ds M" """
-.ds S" """
-.ds N" """""
-.ds T" """""
-.ds L' '
-.ds R' '
-.ds M' '
-.ds S' '
-.ds N' '
-.ds T' '
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` `
+. ds C' '
'br\}
.el\{\
-.ds -- \(em\|
-.tr \*(Tr
-.ds L" ``
-.ds R" ''
-.ds M" ``
-.ds S" ''
-.ds N" ``
-.ds T" ''
-.ds L' `
-.ds R' '
-.ds M' `
-.ds S' '
-.ds N' `
-.ds T' '
-.ds PI \(*p
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
'br\}
-.\" If the F register is turned on, we'll generate
-.\" index entries out stderr for the following things:
-.\" TH Title
-.\" SH Header
-.\" Sh Subsection
-.\" Ip Item
-.\" X<> Xref (embedded
-.\" Of course, you have to process the output yourself
-.\" in some meaninful fashion.
-.if \nF \{
-.de IX
-.tm Index:\\$1\t\\n%\t"\\$2"
-..
-.nr % 0
-.rr F
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr
+.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
+.\" index entries marked with X<> in POD. Of course, you'll have to process
+.\" the output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+. .
+. nr % 0
+. rr F
.\}
-.TH str 3 "14-Jul-2000" "Str 0.9.5" "String Library"
-.UC
-.if n .hy 0
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it
+.\" makes way too many mistakes in technical documents.
+.hy 0
.if n .na
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.de CQ \" put $1 in typewriter font
-.ft CW
-'if n "\c
-'if t \\&\\$1\c
-'if n \\&\\$1\c
-'if n \&"
-\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
-'.ft R
-..
-.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
-. \" AM - accent mark definitions
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
.bd B 3
-. \" fudge factors for nroff and troff
+. \" fudge factors for nroff and troff
.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
.\}
.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
.\}
-. \" simple accents for nroff and troff
+. \" simple accents for nroff and troff
.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds ? ?
-. ds ! !
-. ds /
-. ds q
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
.\}
.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
-. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
-. \" troff and (daisy-wheel) nroff accents
+. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
-.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
-.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
-.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
@@ -162,124 +118,134 @@
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
-.ds oe o\h'-(\w'o'u*4/10)'e
-.ds Oe O\h'-(\w'O'u*4/10)'E
-. \" corrections for vroff
+. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
+. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
-. ds : e
-. ds 8 ss
-. ds v \h'-1'\o'\(aa\(ga'
-. ds _ \h'-1'^
-. ds . \h'-1'.
-. ds 3 3
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-. ds oe oe
-. ds Oe OE
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
.\}
.rm #[ #] #H #V #F C
+.\" ======================================================================
+.\"
+.IX Title "str 3"
+.TH str 3 "14-Jul-2000" "Str 0.9.5" "String Library"
+.UC
.SH "NAME"
-\fBStr\fR \- String Library
+\&\fBStr\fR \- String Library
.SH "VERSION"
-Str 0.9.5 (14-Jul-2000)
+.IX Header "VERSION"
+Str \s-10.9.5 (14-Jul-2000)\s0
.SH "SYNOPSIS"
-\fBstr_len\fR,
-\fBstr_copy\fR,
-\fBstr_dup\fR,
-\fBstr_concat\fR,
-\fBstr_splice\fR,
-\fBstr_compare\fR,
-\fBstr_span\fR,
-\fBstr_locate\fR,
-\fBstr_token\fR,
-\fBstr_parse\fR,
-\fBstr_format\fR,
-\fBstr_hash\fR,
-\fBstr_base64\fR.
+.IX Header "SYNOPSIS"
+\&\fBstr_len\fR,
+\&\fBstr_copy\fR,
+\&\fBstr_dup\fR,
+\&\fBstr_concat\fR,
+\&\fBstr_splice\fR,
+\&\fBstr_compare\fR,
+\&\fBstr_span\fR,
+\&\fBstr_locate\fR,
+\&\fBstr_token\fR,
+\&\fBstr_parse\fR,
+\&\fBstr_format\fR,
+\&\fBstr_hash\fR,
+\&\fBstr_base64\fR.
.SH "DESCRIPTION"
-The \fBStr\fR library is a generic string library written in ANSI C which
+.IX Header "DESCRIPTION"
+The \fBStr\fR library is a generic string library written in \s-1ANSI\s0 C which
provides functions for handling, matching, parsing, searching and
-formatting of C strings. So it can be considered as a superset of POSIX
-\fIstring\fR\|(3), but its main intention is to provide a more convinient and
-compact API plus a more generalized functionality.
+formatting of C strings. So it can be considered as a superset of \s-1POSIX\s0
+\&\fIstring\fR\|(3), but its main intention is to provide a more convinient and
+compact \s-1API\s0 plus a more generalized functionality.
.SH "FUNCTIONS"
-The following functions are provided by the \fBStr\fR API:
+.IX Header "FUNCTIONS"
+The following functions are provided by the \fBStr\fR \s-1API:\s0
.Ip "str_size_t \fBstr_len\fR(const char *\fIs\fR);" 4
+.IX Item "str_size_t str_len(const char *s);"
This function determines the length of string \fIs\fR, i.e., the number
-of characters starting at \fIs\fR that precede the terminating \f(CWNUL\fR
-character. It returns \f(CWNULL\fR if \fIs\fR is \f(CWNULL\fR.
+of characters starting at \fIs\fR that precede the terminating \f(CW\*(C`NUL\*(C'\fR
+character. It returns \f(CW\*(C`NULL\*(C'\fR if \fIs\fR is \f(CW\*(C`NULL\*(C'\fR.
.Ip "char *\fBstr_copy\fR(char *\fIs\fR, const char *\fIt\fR, size_t \fIn\fR);" 4
+.IX Item "char *str_copy(char *s, const char *t, size_t n);"
This copies the characters in string \fIt\fR into the string \fIs\fR, but never more
-than \fIn\fR characters (if \fIn\fR is greater than \f(CW0\fR). The two involved strings
-can overlap and the characters in \fIs\fR are always \f(CWNUL\fR\-terminated. The
+than \fIn\fR characters (if \fIn\fR is greater than \f(CW\*(C`0\*(C'\fR). The two involved strings
+can overlap and the characters in \fIs\fR are always \f(CW\*(C`NUL\*(C'\fR\-terminated. The
string \fIs\fR has to be large enough to hold all characters to be copied.
-function returns \f(CWNULL\fR if \fIs\fR or \fIt\fR are \f(CWNULL\fR. Else it returns the
-pointer to the written \f(CWNUL\fR\-terminating character in \fIs\fR.
+function returns \f(CW\*(C`NULL\*(C'\fR if \fIs\fR or \fIt\fR are \f(CW\*(C`NULL\*(C'\fR. Else it returns the
+pointer to the written \f(CW\*(C`NUL\*(C'\fR\-terminating character in \fIs\fR.
.Ip "char *\fBstr_dup\fR(const char *\fIs\fR, str_size_t \fIn\fR);" 4
+.IX Item "char *str_dup(const char *s, str_size_t n);"
This returns a copy of the characters in string \fIs\fR, but never more than \fIn\fR
-characters if \fIn\fR is greater than \f(CW0\fR. It returns \f(CWNULL\fR if \fIs\fR is
-\f(CWNULL\fR. The returned string has to be deallocated later with \fIfree\fR\|(3).
+characters if \fIn\fR is greater than \f(CW\*(C`0\*(C'\fR. It returns \f(CW\*(C`NULL\*(C'\fR if \fIs\fR is
+\&\f(CW\*(C`NULL\*(C'\fR. The returned string has to be deallocated later with \fIfree\fR\|(3).
.Ip "char *\fBstr_concat\fR(char *\fIs\fR, ...);" 4
+.IX Item "char *str_concat(char *s, ...);"
This functions concatenates the characters of all string arguments into a new
-allocated string and returns this new string. If \fIs\fR is \f(CWNULL\fR the function
-returns \f(CWNULL\fR. Else it returns the pointer to the written final
-\f(CWNUL\fR\-terminating character in \fIs\fR. The returned string later has to be
+allocated string and returns this new string. If \fIs\fR is \f(CW\*(C`NULL\*(C'\fR the function
+returns \f(CW\*(C`NULL\*(C'\fR. Else it returns the pointer to the written final
+\&\f(CW\*(C`NUL\*(C'\fR\-terminating character in \fIs\fR. The returned string later has to be
deallicated with \fIfree\fR\|(3).
.Ip "char *\fBstr_splice\fR(char *\fIs\fR, str_size_t \fIoff\fR, str_size_t \fIn\fR, char *\fIt\fR, str_size_t \fIm\fR);" 4
+.IX Item "char *str_splice(char *s, str_size_t off, str_size_t n, char *t, str_size_t m);"
This splices the string \fIt\fR into string \fIs\fR, i.e., the \fIn\fR characters
at offset \fIoff\fR in \fIs\fR are removed and at their location the string
-\fIt\fR is inserted (or just the first \fIm\fR characters of \fIt\fR if \fIm\fR is
-greater than \f(CW0\fR). It returns \f(CWNULL\fR if \fIs\fR or \fIt\fR are \f(CWNULL\fR.
+\&\fIt\fR is inserted (or just the first \fIm\fR characters of \fIt\fR if \fIm\fR is
+greater than \f(CW\*(C`0\*(C'\fR). It returns \f(CW\*(C`NULL\*(C'\fR if \fIs\fR or \fIt\fR are \f(CW\*(C`NULL\*(C'\fR.
Else the string \fIs\fR is returned. The function supports also the
situation where \fIt\fR is a sub-string of \fIs\fR as long as the area
-\fIs+off\fR...\fIs+off+n\fR and \fIt\fR...\fIt+m\fR do not overlap. The caller
+\&\fIs+off\fR...\fIs+off+n\fR and \fIt\fR...\fIt+m\fR do not overlap. The caller
always has to make sure that enough room exists in \fIs\fR.
.Ip "int \fBstr_compare\fR(const char *\fIs\fR, const char *\fIt\fR, str_size_t \fIn\fR, int \fImode\fR);" 4
+.IX Item "int str_compare(const char *s, const char *t, str_size_t n, int mode);"
This performs a lexicographical comparison of the two strings \fIs\fR
and \fIt\fR (but never compares more than \fIn\fR characters of them)
-and returns one of three return values: a value lower than \f(CW0\fR if
-\fIs\fR is lexicographically lower than \fIt\fR, a vlue of exactly \f(CW0\fR
-if \fIs\fR and \fIt\fR are equal and a value greater than \f(CW0\fR if \fIs\fR is
-lexicographically higher than \fIt\fR. Per default (\fImode\fR is \f(CW0\fR) the
-comparison is case-sensitive, but if \f(CWSTR_NOCASE\fR is used for \fImode\fR
+and returns one of three return values: a value lower than \f(CW\*(C`0\*(C'\fR if
+\&\fIs\fR is lexicographically lower than \fIt\fR, a vlue of exactly \f(CW\*(C`0\*(C'\fR
+if \fIs\fR and \fIt\fR are equal and a value greater than \f(CW\*(C`0\*(C'\fR if \fIs\fR is
+lexicographically higher than \fIt\fR. Per default (\fImode\fR is \f(CW\*(C`0\*(C'\fR) the
+comparison is case-sensitive, but if \f(CW\*(C`STR_NOCASE\*(C'\fR is used for \fImode\fR
the comparison is done in a case-insensitive way.
.Ip "char *\fBstr_span\fR(const char *\fIs\fR, size_t \fIn\fR, const char *\fIcharset\fR, int \fImode\fR);" 4
+.IX Item "char *str_span(const char *s, size_t n, const char *charset, int mode);"
This functions spans a string \fIs\fR according to the characters specified in
-\fIcharset\fR. If \fImode\fR is \f(CW0\fR, this means that \fIs\fR is spanned from left to
-right starting at \fIs\fR (and ending either when reaching the terminating \f(CWNUL\fR
+\&\fIcharset\fR. If \fImode\fR is \f(CW\*(C`0\*(C'\fR, this means that \fIs\fR is spanned from left to
+right starting at \fIs\fR (and ending either when reaching the terminating \f(CW\*(C`NUL\*(C'\fR
character or already after \fIn\fR spanned characters) as long as the characters
of \fIs\fR are contained in \fIcharset\fR.
.Sp
-Alternatively one can use a \fImode\fR of \f(CWSTR_COMPLEMENT\fR to indicate that \fIs\fR
+Alternatively one can use a \fImode\fR of \f(CW\*(C`STR_COMPLEMENT\*(C'\fR to indicate that \fIs\fR
is spanned as long as the characters of \fIs\fR are \fInot\fR contained in
-\fIcharset\fR, i.e., \fIcharset\fR then specifies the complement of the spanning
+\&\fIcharset\fR, i.e., \fIcharset\fR then specifies the complement of the spanning
characters.
.Sp
-In both cases one can additionally \*(L"or\*(R" (with the C operator ``\f(CW|\fR'')
-\f(CWSTR_RIGHT\fR into \fImode\fR to indicate that the spanning is done right to
-left starting at the terminating \f(CWNUL\fR character of \fIs\fR (and ending
+In both cases one can additionally \*(L"or\*(R" (with the C operator ``\f(CW\*(C`|\*(C'\fR'')
+\&\f(CW\*(C`STR_RIGHT\*(C'\fR into \fImode\fR to indicate that the spanning is done right to
+left starting at the terminating \f(CW\*(C`NUL\*(C'\fR character of \fIs\fR (and ending
either when reaching \fIs\fR or already after \fIn\fR spanned characters).
.Ip "char *\fBstr_locate\fR(const char *\fIs\fR, str_size_t \fIn\fR, const char *\fIt\fR);" 4
+.IX Item "char *str_locate(const char *s, str_size_t n, const char *t);"
This functions searches for the (smaller) string \fIt\fR inside (larger) string
-\fIs\fR. If \fIn\fR is not \f(CW0\fR, the search is performed only inside the first \fIn\fR
+\&\fIs\fR. If \fIn\fR is not \f(CW\*(C`0\*(C'\fR, the search is performed only inside the first \fIn\fR
characters of \fIs\fR.
.Ip "char *\fBstr_token\fR(char **\fIs\fR, const char *\fIdelim\fR, const char *\fIquote\fR, const char *\fIcomment\fR, int \fImode\fR);" 4
+.IX Item "char *str_token(char **s, const char *delim, const char *quote, const char *comment, int mode);"
This function considers the string \fIs\fR to consist of a sequence of
zero or more text tokens separated by spans of one or more characters
from the separator string \fIdelim\fR. However, text between matched pairs
of quotemarks (characters in \fIquote\fR) is treated as plain text, never
as delimiter (separator) text. Each call of this function returns a
pointer to the first character of the first token of \fIs\fR. The token is
-\f(CWNUL\fR\-terminated, i.e., the string \fIs\fR is processed in a destructive
+\&\f(CW\*(C`NUL\*(C'\fR\-terminated, i.e., the string \fIs\fR is processed in a destructive
way. If there are quotation marks or escape sequences, the input
string is rewritten with quoted sections and escape sequences properly
interpreted.
@@ -289,39 +255,40 @@
subsequent calls with the same pointer variable \fIs\fR will start
processing from the position immediately after the last returned token.
In this way subsequent calls will work through the string \fIs\fR until no
-tokens remain. When no token remains in \fIs\fR, \f(CWNULL\fR is returned. The
+tokens remain. When no token remains in \fIs\fR, \f(CW\*(C`NULL\*(C'\fR is returned. The
string of token separators (\fIdelim\fR) and the string of quote characters
(\fIquote\fR) may be changed from call to call.
.Sp
If a character in the string \fIs\fR is not quoted or escaped, and is in the
-\fIcomment\fR set, then it is overwritten with a \f(CWNUL\fR character and the rest of
+\&\fIcomment\fR set, then it is overwritten with a \f(CW\*(C`NUL\*(C'\fR character and the rest of
the string is ignored. The characters to be used as quote characters are
specified in the \fIquote\fR set, and must be used in balanced pairs. If there
is more than one flavor of quote character, one kind of quote character may be
used to quote another kind. If an unbalanced quote is found, the function
silently act as if one had been placed at the end of the input string. The
-\fIdelim\fR and \fIquote\fR strings must be disjoint, i.e., they have to share
+\&\fIdelim\fR and \fIquote\fR strings must be disjoint, i.e., they have to share
no characters.
.Sp
The \fImode\fR argument can be used to modify the processing of the string
-(default for \fImode\fR is \f(CW0\fR): \f(CWSTR_STRIPQUOTES\fR forces \fIquote\fR
-characters to be stripped from quoted tokens; \f(CWSTR_BACKSLASHESC\fR
+(default for \fImode\fR is \f(CW\*(C`0\*(C'\fR): \f(CW\*(C`STR_STRIPQUOTES\*(C'\fR forces \fIquote\fR
+characters to be stripped from quoted tokens; \f(CW\*(C`STR_BACKSLASHESC\*(C'\fR
enables the interpretation (and expansion) of backslash escape sequences
-(`\fB\ex\fR') through \s-1ANSI\s0\-C rules; \f(CWSTR_SKIPDELIMS\fR forces that after the
-terminating \f(CWNUL\fR is written and the token returned, further delimiters
+(`\fB\ex\fR') through \s-1ANSI-C\s0 rules; \f(CW\*(C`STR_SKIPDELIMS\*(C'\fR forces that after the
+terminating \f(CW\*(C`NUL\*(C'\fR is written and the token returned, further delimiters
are skipped (this allows one to make sure that the delimiters for
one word don't become part of the next word if one change delimiters
-between calls); and \f(CWSTR_TRIGRAPHS\fR enables the recognition and
+between calls); and \f(CW\*(C`STR_TRIGRAPHS\*(C'\fR enables the recognition and
expansion of \s-1ANSI\s0 C Trigraph sequences (as a side effect this enables
-\f(CWSTR_BACKSLASHESC\fR, too).
+\&\f(CW\*(C`STR_BACKSLASHESC\*(C'\fR, too).
.Ip "int \fBstr_parse\fR(const char *\fIs\fR, const char *\fIpop\fR, ...);" 4
+.IX Item "int str_parse(const char *s, const char *pop, ...);"
This parses the string \fIs\fR according to the parsing operation specified
-by \fIpop\fR. If the parsing operation succeeds, \f(CWTRUE\fR is returned. Else
-\f(CWFALSE\fR is returned.
+by \fIpop\fR. If the parsing operation succeeds, \f(CW\*(C`TRUE\*(C'\fR is returned. Else
+\&\f(CW\*(C`FALSE\*(C'\fR is returned.
.Sp
The \fIpop\fR string usually has one of the following two syntax variants:
-`\fBm\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIflags\fR*\*(R' (for matching operations)
-and `\fBs\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIsubst\fR \fIdelim\fR \fIflags\fR*\*(R' (for
+`\fBm\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIflags\fR*' (for matching operations)
+and `\fBs\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIsubst\fR \fIdelim\fR \fIflags\fR*' (for
substitution operations). For more details about the syntax variants
and semantic of the \fIpop\fR argument see section \fB\s-1GORY\s0 \s-1DETAILS\s0, Parsing
Specification\fR below. The syntax of the \fIregex\fR part in \fIpop\fR is
@@ -329,10 +296,11 @@
complete and gory details see \fIperlre\fR\|(1). A brief summary you can find
under section \fB\s-1GORY\s0 \s-1DETAILS\s0, Perl Regular Expressions\fR below.
.Ip "int \fBstr_format\fR(char *\fIs\fR, str_size_t \fIn\fR, const char *\fIfmt\fR, ...);" 4
+.IX Item "int str_format(char *s, str_size_t n, const char *fmt, ...);"
This formats a new string according to \fIfmt\fR and optionally following
arguments and writes it into the string \fIs\fR, but never more than \fIn\fR
characters at all. It returns the number of written characters. If \fIs\fR is
-\f(CWNULL\fR it just calculates the number of characters which would be written.
+\&\f(CW\*(C`NULL\*(C'\fR it just calculates the number of characters which would be written.
.Sp
The function generates the output string under the control of the \fIfmt\fR
format string that specifies how subsequent arguments (or arguments accessed
@@ -346,40 +314,44 @@
introduced by the character \fB%\fR. The arguments must correspond properly
(after type promotion) with the conversion specifier. Which conversion
specifications are supported are described in detail under \fB\s-1GORY\s0
-\s-1DETAILS\s0, Format Specification\fR below.
+\&\s-1DETAILS\s0, Format Specification\fR below.
.Ip "unsigned long \fBstr_hash\fR(const char *\fIs\fR, str_size_t \fIn\fR, int \fImode\fR);" 4
+.IX Item "unsigned long str_hash(const char *s, str_size_t n, int mode);"
This function calculates a hash value of string \fIs\fR (or of its first \fIn\fR
-characters if \fIn\fR is equal to \f(CW0\fR). The following hashing functions
+characters if \fIn\fR is equal to \f(CW\*(C`0\*(C'\fR). The following hashing functions
are supported and can be selected with \fImode\fR: \s-1STR_HASH_DJBX33\s0 (Daniel
J. Berstein, Times 33 Hash with Addition), \s-1STR_HASH_BJDDJ\s0 (Bob
Jenkins, Dr. Dobbs Journal), and \s-1STR_HASH_MACRC32\s0 (Mark Adler, Cyclic
-Redundancy Check with 32-Bit). This function is intended for fast use
+Redundancy Check with 32\-Bit). This function is intended for fast use
in hashing algorithms and \fInot\fR for use as cryptographically strong
message digests.
.Ip "int \fBstr_base64\fR(char *\fIs\fR, str_size_t \fIn\fR, unsigned char *\fIucp\fR, str_size_t \fIucn\fR, int \fImode\fR);" 4
+.IX Item "int str_base64(char *s, str_size_t n, unsigned char *ucp, str_size_t ucn, int mode);"
This function Base64 encodes \fIucn\fR bytes starting at \fIucp\fR and writes
the resulting string into \fIs\fR (but never more than \fIn\fR characters are
-written). The \fImode\fR for this operation has to be \f(CWSTR_BASE64_ENCODE\fR.
-Additionally one can \s-1OR\s0 the value \f(CWSTR_BASE64_STRICT\fR to enable strict
+written). The \fImode\fR for this operation has to be \f(CW\*(C`STR_BASE64_ENCODE\*(C'\fR.
+Additionally one can \s-1OR\s0 the value \f(CW\*(C`STR_BASE64_STRICT\*(C'\fR to enable strict
encoding where after every 72th output character a newline character is
inserted. The function returns the number of output characters written.
-If \fIs\fR is \f(CWNULL\fR the function just calculates the number of required
+If \fIs\fR is \f(CW\*(C`NULL\*(C'\fR the function just calculates the number of required
output characters.
.Sp
-Alternatively, if \fImode\fR is \f(CWSTR_BASE64_DECODE\fR the string \fIs\fR (or
-the first \fIn\fR characters only if \fIn\fR is not \f(CW0\fR) is decoded and the
-output bytes written at \fIucp\fR. Again, if \fIucp\fR is \f(CWNULL\fR only the
+Alternatively, if \fImode\fR is \f(CW\*(C`STR_BASE64_DECODE\*(C'\fR the string \fIs\fR (or
+the first \fIn\fR characters only if \fIn\fR is not \f(CW\*(C`0\*(C'\fR) is decoded and the
+output bytes written at \fIucp\fR. Again, if \fIucp\fR is \f(CW\*(C`NULL\*(C'\fR only the
number of required output bytes are calculated.
.SH "GORY DETAILS"
+.IX Header "GORY DETAILS"
In this part of the documentation more complex topics are documented in
detail.
.Sh "Perl Regular Expressions"
+.IX Subsection "Perl Regular Expressions"
The regular expressions used in \fBStr\fR are more or less Perl compatible
(they are provided by a stripped down and built-in version of the
-\fI\s-1PCRE\s0\fR library). So the syntax description in \fIperlre\fR\|(1) applies
+\&\fI\s-1PCRE\s0\fR library). So the syntax description in \fIperlre\fR\|(1) applies
and don't has to be repeated here again. For a deeper understanding
and details you should have a look at the book `\fIMastering Regular
-Expressions\fR\*(R' (see also the \fIperlbook\fR\|(1) manpage) by \fIJeffrey Friedl\fR.
+Expressions\fR' (see also the \fIperlbook\fR\|(1) manpage) by \fIJeffrey Friedl\fR.
For convinience reasons we give you only a brief summary of Perl
compatible regular expressions:
.PP
@@ -465,74 +437,84 @@
\& (?imsx-imsx) One or more embedded pattern-match modifiers
.Ve
.Sh "Parsing Specification"
+.IX Subsection "Parsing Specification"
The \fBstr_parse\fR(const char *\fIs\fR, const char *\fIpop\fR, ...) function
is a very flexible but complex one. The argument \fIs\fR is the string on
which the parsing operation specified by argument \fIpop\fR is applied.
-The parsing semantics are highly influenced by Perl's `\fB=~\fR\*(R' matching
+The parsing semantics are highly influenced by Perl's `\fB=~\fR' matching
operator, because one of the main goals of \fIstr_parse\fR\|(3) is to allow one
to rewrite typical Perl matching constructs into C.
.PP
Now to the gory details. In general, the \fIpop\fR argument of \fIstr_parse\fR\|(3)
has one of the following two syntax variants:
-.Ip "\fBMatching:\fR `\fBm\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIflags\fR*': " 4
+.Ip "\fBMatching:\fR `\fBm\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIflags\fR*':" 4
+.IX Item "Matching: `m delim regex delim flags*':"
This matches \fIs\fR against the Perl-style regular expression \fIregex\fR
under the control of zero or more \fIflags\fR which control the parsing
-semantics. The stripped down \fIpop\fR syntax `\fIregex\fR\*(R' is equivalent to
-`\fBm/\fR\fIregex\fR\fB/\fR\*(R'.
+semantics. The stripped down \fIpop\fR syntax `\fIregex\fR' is equivalent to
+`\fBm/\fR\fIregex\fR\fB/\fR'.
.Sp
For each grouping pair of parenthesis in \fIregex\fR, the text in \fIs\fR
which was grouped by the parenthesis is extracted into new strings.
These per default are allocated as seperate strings and returned to the
-caller through following `\fBchar **\fR\*(R' arguments. The caller is required
+caller through following `\fBchar **\fR' arguments. The caller is required
to \fIfree\fR\|(3) them later.
-.Ip "\fBSubstitution:\fR `\fBs\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIsubst\fR \fIdelim\fR \fIflags\fR*': " 4
+.Ip "\fBSubstitution:\fR `\fBs\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIsubst\fR \fIdelim\fR \fIflags\fR*':" 4
+.IX Item "Substitution: `s delim regex delim subst delim flags*':"
This matches \fIs\fR against the Perl-style regular expression \fIregex\fR
under the control of zero or more \fIflags\fR which control the parsing
semantics. As a result of the operation, a new string formed which
consists of \fIs\fR but with the part which matched \fIregex\fR replaced by
-\fIsubst\fR. The result string is returned to the caller through a `\fBchar
-**\fR\*(R' argument. The caller is required to \fIfree\fR\|(3) this later.
+\&\fIsubst\fR. The result string is returned to the caller through a `\fBchar
+**\fR' argument. The caller is required to \fIfree\fR\|(3) this later.
.Sp
For each grouping pair of parenthesis in \fIregex\fR, the text in \fIs\fR
which was grouped by the parenthesis is extracted into new strings
-and can be referenced for expansion via `\fB$n\fR\*(R' (n=1,..) in \fIsubst\fR.
-Additionally any \fIstr_format\fR\|(3) style `\fB%\fR\*(R' constructs in \fIsubst\fR are
+and can be referenced for expansion via `\fB$n\fR' (n=1,..) in \fIsubst\fR.
+Additionally any \fIstr_format\fR\|(3) style `\fB%\fR' constructs in \fIsubst\fR are
expanded through additional caller supplied arguments.
.PP
The following \fIflags\fR are supported:
.Ip "\fBb\fR" 4
-If the \fIbundle\fR flag `\fBb\fR\*(R' is specified, the extracted strings are
+.IX Item "b"
+If the \fIbundle\fR flag `\fBb\fR' is specified, the extracted strings are
bundled together into a single chunk of memory and its address is
-returned to the caller with a additional `\fBchar **\fR\*(R' argument which has
+returned to the caller with a additional `\fBchar **\fR' argument which has
to preceed the regular string arguments. The caller then has to \fIfree\fR\|(3)
only this chunk of memory in order to free all extracted strings at
once.
.Ip "\fBi\fR" 4
-If the case-\fIinsensitive\fR flag `\fBi\fR\*(R' is specified, \fIregex\fR
+.IX Item "i"
+If the case-\fIinsensitive\fR flag `\fBi\fR' is specified, \fIregex\fR
is matched in case-insensitive way.
.Ip "\fBo\fR" 4
-If the \fIonce\fR flag `\fBo\fR\*(R' is specified, this indicates to the \fBStr\fR
+.IX Item "o"
+If the \fIonce\fR flag `\fBo\fR' is specified, this indicates to the \fBStr\fR
library that the whole \fIpop\fR string is constant and that its internal
pre-processing (it is compiled into a deterministic finite automaton
(\s-1DFA\s0) internally) has to be done only once (the \fBStr\fR library then
caches the \s-1DFA\s0 which corresponds to the \fIpop\fR argument).
.Ip "\fBx\fR" 4
-If the \fIextended\fR flag `\fBx\fR\*(R' is specified, the \fIregex\fR's legibility
+.IX Item "x"
+If the \fIextended\fR flag `\fBx\fR' is specified, the \fIregex\fR's legibility
is extended by permitting embedded whitespace and comments to allow one
to write down complex regular expressions more cleary and even in a
documented way.
.Ip "\fBm\fR" 4
-If the \fImultiple\fR lines flag `\fBm\fR\*(R' is specified, the string \fIs\fR is
+.IX Item "m"
+If the \fImultiple\fR lines flag `\fBm\fR' is specified, the string \fIs\fR is
treated as multiple lines. That is, this changes the regular expression
-meta characters `\fB^\fR\*(R' and `\fB$\fR\*(R' from matching at only the very start
+meta characters `\fB^\fR' and `\fB$\fR' from matching at only the very start
or end of the string \fIs\fR to the start or end of any line anywhere
within the string \fIs\fR.
.Ip "\fBs\fR" 4
-If the \fIsingle\fR line flag `\fBs\fR\*(R' is specified, the string \fIs\fR is
+.IX Item "s"
+If the \fIsingle\fR line flag `\fBs\fR' is specified, the string \fIs\fR is
treated as single line. That is, this changes the regular expression
-meta character `\fB.\fR\*(R' to match any character whatsoever, even a newline,
+meta character `\fB.\fR' to match any character whatsoever, even a newline,
which it normally would not match.
.SH "CONVERSION SPECIFICATION"
+.IX Header "CONVERSION SPECIFICATION"
In the format string of \fIstr_format\fR\|(3) each conversion specification is
introduced by the character \fB%\fR. After the \fB%\fR, the following appear
in sequence:
@@ -546,7 +528,7 @@
Zero or more of the following flags:
.Sp
A \fB#\fR character specifying that the value should be converted to an
-``alternate form'\*(R'. For \fBc\fR, \fBd\fR, \fBi\fR, \fBn\fR, \fBp\fR, \fBs\fR, and \fBu\fR,
+``alternate form''. For \fBc\fR, \fBd\fR, \fBi\fR, \fBn\fR, \fBp\fR, \fBs\fR, and \fBu\fR,
conversions, this option has no effect. For \fBo\fR conversions, the precision
of the number is increased to force the first character of the output string
to a zero (except if a zero value is printed with an explicit precision of
@@ -557,21 +539,21 @@
conversions only if a digit follows). For \fBg\fR and \fBG\fR conversions, trailing
zeros are not removed from the result as they would otherwise be.
.Sp
-A zero `\fB0\fR\*(R' character specifying zero padding. For all conversions except
-\fBn\fR, the converted value is padded on the left with zeros rather than blanks.
+A zero `\fB0\fR' character specifying zero padding. For all conversions except
+\&\fBn\fR, the converted value is padded on the left with zeros rather than blanks.
If a precision is given with a numeric conversion (\fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR,
-\fBi\fR, \fBx\fR, and \fBX\fR), the `\fB0\fR\*(R' flag is ignored.
+\&\fBi\fR, \fBx\fR, and \fBX\fR), the `\fB0\fR' flag is ignored.
.Sp
-A negative field width flag `\fB\-\fR\*(R' indicates the converted value is to be left
+A negative field width flag `\fB-\fR' indicates the converted value is to be left
adjusted on the field boundary. Except for \fBn\fR conversions, the converted
value is padded on the right with blanks, rather than on the left with blanks
-or zeros. A `\fB\-\fR\*(R' overrides a `\fB0\fR\*(R' if both are given.
+or zeros. A `\fB-\fR' overrides a `\fB0\fR' if both are given.
.Sp
A space, specifying that a blank should be left before a positive number
produced by a signed conversion (\fBd\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBg\fR, \fBG\fR, or \fBi\fR).
.Sp
-A `\fB+\fR\*(R' character specifying that a sign always be placed before a number
-produced by a signed conversion. A `\fB+\fR\*(R' overrides a space if both are used.
+A `\fB+\fR' character specifying that a sign always be placed before a number
+produced by a signed conversion. A `\fB+\fR' overrides a space if both are used.
.Ip "o" 4
An optional decimal digit string specifying a minimum field width.
If the converted value has fewer characters than the field width, it will
@@ -579,38 +561,38 @@
flag has been given) to fill out
the field width.
.Ip "o" 4
-An optional precision, in the form of a period `\fB.\fR\*(R' followed by an
+An optional precision, in the form of a period `\fB.\fR' followed by an
optional digit string. If the digit string is omitted, the precision is
taken as zero. This gives the minimum number of digits to appear for
-\fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, and \fBX\fR conversions, the number of digits
+\&\fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, and \fBX\fR conversions, the number of digits
to appear after the decimal-point for \fBe\fR, \fBE\fR, and \fBf\fR conversions,
the maximum number of significant digits for \fBg\fR and \fBG\fR conversions,
or the maximum number of characters to be printed from a string for \fBs\fR
conversions.
.Ip "o" 4
The optional character \fBh\fR, specifying that a following \fBd\fR, \fBi\fR, \fBo\fR,
-\fBu\fR, \fBx\fR, or \fBX\fR conversion corresponds to a `\f(CWshort int\fR\*(R' or `\f(CWunsigned
-short int\fR\*(R' argument, or that a following \fBn\fR conversion corresponds to a
-pointer to a `\f(CWshort int\fR argument.
+\&\fBu\fR, \fBx\fR, or \fBX\fR conversion corresponds to a `\f(CW\*(C`short int\*(C'\fR' or `\f(CW\*(C`unsigned
+short int\*(C'\fR' argument, or that a following \fBn\fR conversion corresponds to a
+pointer to a `\f(CW\*(C`short int\*(C'\fR argument.
.Ip "o" 4
The optional character \fBl\fR (ell) specifying that a following \fBd\fR, \fBi\fR,
-\fBo\fR, \fBu\fR, \fBx\fR, or \fBX\fR conversion applies to a pointer to a `\f(CWlong int\fR\*(R'
-or `\f(CWunsigned long int\fR\*(R' argument, or that a following \fBn\fR conversion
-corresponds to a pointer to a `\f(CWlong int\fR argument.
+\&\fBo\fR, \fBu\fR, \fBx\fR, or \fBX\fR conversion applies to a pointer to a `\f(CW\*(C`long int\*(C'\fR'
+or `\f(CW\*(C`unsigned long int\*(C'\fR' argument, or that a following \fBn\fR conversion
+corresponds to a pointer to a `\f(CW\*(C`long int\*(C'\fR argument.
.Ip "o" 4
The optional character \fBq\fR, specifying that a following \fBd\fR, \fBi\fR, \fBo\fR,
-\fBu\fR, \fBx\fR, or \fBX\fR conversion corresponds to a `\f(CWquad int\fR\*(R' or `\f(CWunsigned
-quad int\fR\*(R' argument, or that a following \fBn\fR conversion corresponds to a
-pointer to a `\f(CWquad int\fR\*(R' argument.
+\&\fBu\fR, \fBx\fR, or \fBX\fR conversion corresponds to a `\f(CW\*(C`quad int\*(C'\fR' or `\f(CW\*(C`unsigned
+quad int\*(C'\fR' argument, or that a following \fBn\fR conversion corresponds to a
+pointer to a `\f(CW\*(C`quad int\*(C'\fR' argument.
.Ip "o" 4
The character \fBL\fR specifying that a following \fBe\fR, \fBE\fR, \fBf\fR, \fBg\fR, or \fBG\fR
-conversion corresponds to a `\f(CWlong double\fR\*(R' argument.
+conversion corresponds to a `\f(CW\*(C`long double\*(C'\fR' argument.
.Ip "o" 4
A character that specifies the type of conversion to be applied.
.PP
-A field width or precision, or both, may be indicated by an asterisk `\fB*\fR\*(R' or
-an asterisk followed by one or more decimal digits and a `\fB$\fR\*(R' instead of a
-digit string. In this case, an `\f(CWint\fR\*(R' argument supplies the field width or
+A field width or precision, or both, may be indicated by an asterisk `\fB*\fR' or
+an asterisk followed by one or more decimal digits and a `\fB$\fR' instead of a
+digit string. In this case, an `\f(CW\*(C`int\*(C'\fR' argument supplies the field width or
precision. A negative field width is treated as a left adjustment flag
followed by a positive field width; a negative precision is treated as though
it were missing. If a single format directive mixes positional (`\fBnn$\fR') and
@@ -618,34 +600,39 @@
.PP
The conversion specifiers and their meanings are:
.Ip "\fBdiouxX\fR" 4
-The `\f(CWint\fR\*(R' (or appropriate variant) argument is converted to signed decimal
+.IX Item "diouxX"
+The `\f(CW\*(C`int\*(C'\fR' (or appropriate variant) argument is converted to signed decimal
(\fBd\fR and \fBi\fR), unsigned octal (\fBo\fR), unsigned decimal (\fBu\fR), or unsigned
hexadecimal (\fBx\fR and \fBX\fR) notation. The letters \fBabcdef\fR are used for \fBx\fR
conversions; the letters \fB\s-1ABCDEF\s0\fR are used for \fBX\fR conversions. The
precision, if any, gives the minimum number of digits that must appear; if the
converted value requires fewer digits, it is padded on the left with zeros.
.Ip "\fB\s-1DOU\s0\fR" 4
-The `\f(CWlong int\fR argument is converted to signed decimal, unsigned octal, or
+.IX Item "DOU"
+The `\f(CW\*(C`long int\*(C'\fR argument is converted to signed decimal, unsigned octal, or
unsigned decimal, as if the format had been \fBld\fR, \fBlo\fR, or \fBlu\fR
respectively. These conversion characters are deprecated, and will eventually
disappear.
.Ip "\fBeE\fR" 4
-The `\f(CWdouble\fR\*(R' argument is rounded and converted in the style
-`[\-]d.ddd\fBe\fR+\-dd\*(R' where there is one digit before the decimal-point character
+.IX Item "eE"
+The `\f(CW\*(C`double\*(C'\fR' argument is rounded and converted in the style
+`[\-]d.ddd\fBe\fR+\-dd' where there is one digit before the decimal-point character
and the number of digits after it is equal to the precision; if the precision
is missing, it is taken as 6; if the precision is zero, no decimal-point
character appears. An \fBE\fR conversion uses the letter \fBE\fR (rather than \fBe\fR)
to introduce the exponent. The exponent always contains at least two digits;
if the value is zero, the exponent is 00.
.Ip "\fBf\fR" 4
-The `\f(CWdouble\fR\*(R' argument is rounded and converted to decimal notation in the
-style `[\-]ddd.ddd>\*(R' where the number of digits after the decimal-point
+.IX Item "f"
+The `\f(CW\*(C`double\*(C'\fR' argument is rounded and converted to decimal notation in the
+style `[\-]ddd.ddd>' where the number of digits after the decimal-point
character is equal to the precision specification. If the precision is
missing, it is taken as 6; if the precision is explicitly zero, no
decimal-point character appears. If a decimal point appears, at least one
digit appears before it.
.Ip "\fBg\fR" 4
-The `\f(CWdouble\fR\*(R' argument is converted in style \fBf\fR or \fBe\fR (or \fBE\fR for \fBG\fR
+.IX Item "g"
+The `\f(CW\*(C`double\*(C'\fR' argument is converted in style \fBf\fR or \fBe\fR (or \fBE\fR for \fBG\fR
conversions). The precision specifies the number of significant digits. If
the precision is missing, 6 digits are given; if the precision is zero, it is
treated as 1. Style \fBe\fR is used if the exponent from its conversion is less
@@ -653,34 +640,40 @@
from the fractional part of the result; a decimal point appears only if it is
followed by at least one digit.
.Ip "\fBc\fR" 4
-The `\f(CWint\fR\*(R' argument is converted to an `\f(CWunsigned char\fR, and the resulting
+.IX Item "c"
+The `\f(CW\*(C`int\*(C'\fR' argument is converted to an `\f(CW\*(C`unsigned char\*(C'\fR, and the resulting
character is written.
.Ip "\fBs\fR" 4
-The `\f(CWchar *\fR\*(R' argument is expected to be a pointer to an array of character
+.IX Item "s"
+The `\f(CW\*(C`char *\*(C'\fR' argument is expected to be a pointer to an array of character
type (pointer to a string). Characters from the array are written up to (but
-not including) a terminating \f(CWNUL\fR character; if a precision is specified, no
+not including) a terminating \f(CW\*(C`NUL\*(C'\fR character; if a precision is specified, no
more than the number specified are written. If a precision is given, no null
character need be present; if the precision is not specified, or is greater
-than the size of the array, the array must contain a terminating \f(CWNUL\fR
+than the size of the array, the array must contain a terminating \f(CW\*(C`NUL\*(C'\fR
character.
.Ip "\fBp\fR" 4
-The `\f(CWvoid *\fR pointer argument is printed in hexadecimal (as if by `\fB%#x\fR\*(R'
-or `\f(CW%#lx\fR).
+.IX Item "p"
+The `\f(CW\*(C`void *\*(C'\fR pointer argument is printed in hexadecimal (as if by `\fB%#x\fR'
+or `\f(CW\*(C`%#lx\*(C'\fR).
.Ip "\fBn\fR" 4
+.IX Item "n"
The number of characters written so far is stored into the integer indicated
-by the `\f(CWint *\fR\*(R' (or variant) pointer argument. No argument is converted.
+by the `\f(CW\*(C`int *\*(C'\fR' (or variant) pointer argument. No argument is converted.
.Ip "\fB%\fR" 4
-A `\fB%\fR\*(R' is written. No argument is converted. The complete conversion
+.IX Item "%"
+A `\fB%\fR' is written. No argument is converted. The complete conversion
specification is `\fB%%\fR.
.PP
In no case does a non-existent or small field width cause truncation of a
field; if the result of a conversion is wider than the field width, the field
is expanded to contain the conversion result.
.SH "EXAMPLES"
+.IX Header "EXAMPLES"
In the following a few snippets of selected use cases of \fBStr\fR are
presented:
.Ip "\fBSplice a String into Another\fR" 4
-.Sp
+.IX Item "Splice a String into Another"
.Vb 5
\& char *v1 = "foo bar quux";
\& char *v2 = "baz";
@@ -689,7 +682,7 @@
\& ....
.Ve
.Ip "\fBTokenize a String\fR" 4
-.Sp
+.IX Item "Tokenize a String"
.Vb 10
\& char *var = " foo \et " bar 'baz'" q'uu'x #comment";
\& char *tok, *p;
@@ -703,7 +696,7 @@
\& }
.Ve
.Ip "\fBMatch a String\fR" 4
-.Sp
+.IX Item "Match a String"
.Vb 5
\& char *var = "foo:bar";
\& if (str_parse(var, "^.+?:.+$/)) {
@@ -712,7 +705,7 @@
\& }
.Ve
.Ip "\fBMatch a String and Go Ahead with Details\fR" 4
-.Sp
+.IX Item "Match a String and Go Ahead with Details"
.Vb 10
\& char *var = "foo:bar";
\& char *cp, *v1, *v2;
@@ -726,7 +719,7 @@
\& }
.Ve
.Ip "\fBSubstitute Text in a String\fR" 4
-.Sp
+.IX Item "Substitute Text in a String"
.Vb 8
\& char *var = "foo:bar";
\& char *subst = "quux";
@@ -738,7 +731,7 @@
\& free(new);
.Ve
.Ip "\fBFormat a String\fR" 4
-.Sp
+.IX Item "Format a String"
.Vb 6
\& char *v0 = "abc..."; /* length not guessable */
\& char *v1 = "foo";
@@ -756,145 +749,24 @@
\& free(cp);
.Ve
.SH "SEE ALSO"
-\fIstring\fR\|(3), \fIprintf\fR\|(3), \fIperlre\fR\|(1).
+.IX Header "SEE ALSO"
+\&\fIstring\fR\|(3), \fIprintf\fR\|(3), \fIperlre\fR\|(1).
.SH "HISTORY"
+.IX Header "HISTORY"
The \fBStr\fR library was written in November and December 1999 by Ralf
S. Engelschall. As building blocks various existing code was used and
recycled: for the \fIstr_token\fR\|(3) implementation an anchient \fIstrtok\fR\|(3)
flavor from William Deich 1991 was cleaned up and adjusted. As the
background parsing engine for \fIstr_parse\fR\|(3) a heavily stripped down
-version of Philip Hazel's PCRE 2.08 library was used. The \fIstr_format\fR\|(3)
-implementation was based on Panos Tsirigotis\*(R' \fIsprintf\fR\|(3) code as
+version of Philip Hazel's \s-1PCRE\s0 2.08 library was used. The \fIstr_format\fR\|(3)
+implementation was based on Panos Tsirigotis' \fIsprintf\fR\|(3) code as
adjusted by the Apache Software Foundation 1998. The formatting engine
was stripped down and enhanced to support internal extensions which were
required by \fIstr_format\fR\|(3) and \fIstr_parse\fR\|(3).
.SH "AUTHOR"
-.PP
+.IX Header "AUTHOR"
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
.Ve
-
-.rn }` ''
-.IX Title "str 3"
-.IX Name "B<Str> - String Library"
-
-.IX Header "NAME"
-
-.IX Header "VERSION"
-
-.IX Header "SYNOPSIS"
-
-.IX Header "DESCRIPTION"
-
-.IX Header "FUNCTIONS"
-
-.IX Item "str_size_t \fBstr_len\fR(const char *\fIs\fR);"
-
-.IX Item "char *\fBstr_copy\fR(char *\fIs\fR, const char *\fIt\fR, size_t \fIn\fR);"
-
-.IX Item "char *\fBstr_dup\fR(const char *\fIs\fR, str_size_t \fIn\fR);"
-
-.IX Item "char *\fBstr_concat\fR(char *\fIs\fR, ...);"
-
-.IX Item "char *\fBstr_splice\fR(char *\fIs\fR, str_size_t \fIoff\fR, str_size_t \fIn\fR, char *\fIt\fR, str_size_t \fIm\fR);"
-
-.IX Item "int \fBstr_compare\fR(const char *\fIs\fR, const char *\fIt\fR, str_size_t \fIn\fR, int \fImode\fR);"
-
-.IX Item "char *\fBstr_span\fR(const char *\fIs\fR, size_t \fIn\fR, const char *\fIcharset\fR, int \fImode\fR);"
-
-.IX Item "char *\fBstr_locate\fR(const char *\fIs\fR, str_size_t \fIn\fR, const char *\fIt\fR);"
-
-.IX Item "char *\fBstr_token\fR(char **\fIs\fR, const char *\fIdelim\fR, const char *\fIquote\fR, const char *\fIcomment\fR, int \fImode\fR);"
-
-.IX Item "int \fBstr_parse\fR(const char *\fIs\fR, const char *\fIpop\fR, ...);"
-
-.IX Item "int \fBstr_format\fR(char *\fIs\fR, str_size_t \fIn\fR, const char *\fIfmt\fR, ...);"
-
-.IX Item "unsigned long \fBstr_hash\fR(const char *\fIs\fR, str_size_t \fIn\fR, int \fImode\fR);"
-
-.IX Item "int \fBstr_base64\fR(char *\fIs\fR, str_size_t \fIn\fR, unsigned char *\fIucp\fR, str_size_t \fIucn\fR, int \fImode\fR);"
-
-.IX Header "GORY DETAILS"
-
-.IX Subsection "Perl Regular Expressions"
-
-.IX Subsection "Parsing Specification"
-
-.IX Item "\fBMatching:\fR `\fBm\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIflags\fR*': "
-
-.IX Item "\fBSubstitution:\fR `\fBs\fR \fIdelim\fR \fIregex\fR \fIdelim\fR \fIsubst\fR \fIdelim\fR \fIflags\fR*': "
-
-.IX Item "\fBb\fR"
-
-.IX Item "\fBi\fR"
-
-.IX Item "\fBo\fR"
-
-.IX Item "\fBx\fR"
-
-.IX Item "\fBm\fR"
-
-.IX Item "\fBs\fR"
-
-.IX Header "CONVERSION SPECIFICATION"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "o"
-
-.IX Item "\fBdiouxX\fR"
-
-.IX Item "\fB\s-1DOU\s0\fR"
-
-.IX Item "\fBeE\fR"
-
-.IX Item "\fBf\fR"
-
-.IX Item "\fBg\fR"
-
-.IX Item "\fBc\fR"
-
-.IX Item "\fBs\fR"
-
-.IX Item "\fBp\fR"
-
-.IX Item "\fBn\fR"
-
-.IX Item "\fB%\fR"
-
-.IX Header "EXAMPLES"
-
-.IX Item "\fBSplice a String into Another\fR"
-
-.IX Item "\fBTokenize a String\fR"
-
-.IX Item "\fBMatch a String\fR"
-
-.IX Item "\fBMatch a String and Go Ahead with Details\fR"
-
-.IX Item "\fBSubstitute Text in a String\fR"
-
-.IX Item "\fBFormat a String\fR"
-
-.IX Header "SEE ALSO"
-
-.IX Header "HISTORY"
-
-.IX Header "AUTHOR"
-
|
