.TH "MCHARS_ALLOC" "3" "$Mdocdate: October 26 2014 $" "Debian" "Library Functions Manual"
.nh
.if n .ad l
.SH "NAME"
\fBmchars_alloc\fR,
\fBmchars_free\fR,
\fBmchars_num2char\fR,
\fBmchars_num2uc\fR,
\fBmchars_spec2cp\fR,
\fBmchars_spec2str\fR
\- character table for mandoc
.SH "LIBRARY"
Mandoc Macro Compiler Library (libmandoc, \-lmandoc)
.SH "SYNOPSIS"
\fB#include <sys/types.h>\fR
.br
\fB#include <mandoc.h>\fR
.sp
\fIstruct mchars *\fR
.PD 0
.HP 4n
\fBmchars_alloc\fR(\fIvoid\fR);
.PD
.PP
\fIvoid\fR
.PD 0
.HP 4n
\fBmchars_free\fR(\fIstruct\ mchars\ *table\fR);
.PD
.PP
\fIchar\fR
.PD 0
.HP 4n
\fBmchars_num2char\fR(\fIconst\ char\ *decimal\fR,
\fIsize_t\ sz\fR);
.PD
.PP
\fIint\fR
.PD 0
.HP 4n
\fBmchars_num2uc\fR(\fIconst\ char\ *hexadecimal\fR,
\fIsize_t\ sz\fR);
.PD
.PP
\fIint\fR
.PD 0
.HP 4n
\fBmchars_spec2cp\fR(\fIconst\ struct\ mchars\ *table\fR,
\fIconst\ char\ *name\fR,
\fIsize_t\ sz\fR);
.PD
.PP
\fIconst char *\fR
.PD 0
.HP 4n
\fBmchars_spec2str\fR(\fIconst\ struct\ mchars\ *table\fR,
\fIconst\ char\ *name\fR,
\fIsize_t\ sz\fR,
\fIsize_t\ *rsz\fR);
.PD
.PP
\fIconst char *\fR
.PD 0
.HP 4n
\fBmchars_uc2str\fR(\fIint\ codepoint\fR);
.PD
.SH "DESCRIPTION"
These functions translate Unicode character numbers and
roff(7)
character names into glyphs.
See
mandoc_char(7)
for a list of
roff(7)
special characters.
These functions are intended for external use by programs formatting
mdoc(7)
and
man(7)
pages for output, for example the
mandoc(1)
output formatter modules and
makewhatis(8).
The
\fIdecimal\fR,
\fIhexadecimal\fR,
\fIname\fR,
and
\fIsize\fR
input arguments are usually obtained from the
mandoc_escape(3)
parser function.
.PP
The function
\fBmchars_num2char\fR()
converts a
\fIdecimal\fR
string representation of a character number consisting of
\fIsz\fR
digits into a printable ASCII character.
If the input string is non-numeric or does not represent a printable
ASCII character, the NUL character
(\(oq\e0\(cq)
is returned.
For example, the
mandoc(1)
\fB\-Tascii\fR,
\fB\-Tutf8\fR,
and
\fB\-Thtml\fR
output modules use this function to render
roff(7)
\fB\eN\fR
escape sequences.
.PP
The function
\fBmchars_num2uc\fR()
converts a
\fIhexadecimal\fR
string representation of a Unicode codepoint consisting of
\fIsz\fR
digits into an integer representation.
If the input string is non-numeric or represents an ASCII character,
the NUL character
(\(oq\e0\(cq)
is returned.
For example, the
mandoc(1)
\fB\-Tutf8\fR
and
\fB\-Thtml\fR
output modules use this function to render
roff(7)
\fB\e[u\fR\fIXXXX\fR\fB\&]\fR
and
\fB\eC\(aqu\fR\fIXXXX\fR\fB\(aq\fR
escape sequences.
.PP
The function
\fBmchars_alloc\fR()
allocates an opaque
\fIstruct mchars *\fR
table object for subsequent use by the following two lookup functions.
When no longer needed, this object can be destroyed with
\fBmchars_free\fR().
.PP
The function
\fBmchars_spec2cp\fR()
looks up a
roff(7)
special character
\fIname\fR
consisting of
\fIsz\fR
characters in the
\fItable\fR
and returns the corresponding Unicode codepoint.
If the
\fIname\fR
is not recognized, \-1 is returned.
For example, the
mandoc(1)
\fB\-Tutf8\fR
and
\fB\-Thtml\fR
output modules use this function to render
roff(7)
\fB\e[\fR\fIname\fR\fB\&]\fR
and
\fB\eC\(aq\fR\fIname\fR\fB\(aq\fR
escape sequences.
.PP
The function
\fBmchars_spec2str\fR()
looks up a
roff(7)
special character
\fIname\fR
consisting of
\fIsz\fR
characters in the
\fItable\fR
and returns an ASCII string representation.
The length of the representation is returned in
\fIrsz\fR.
In many cases, the meaning of such ASCII representations
is not quite obvious, so using
roff(7)
special characters in documents intended for ASCII rendering
is usually a bad idea.
If the
\fIname\fR
is not recognized,
\fRNULL\fR
is returned.
For example,
makewhatis(8)
and the
mandoc(1)
\fB\-Tascii\fR
output module use this function to render
roff(7)
\fB\e[\fR\fIname\fR\fB\&]\fR
and
\fB\eC\(aq\fR\fIname\fR\fB\(aq\fR
escape sequences.
.PP
The function
\fBmchars_uc2str\fR()
performs a reverse lookup of the Unicode
\fIcodepoint\fR
and returns an ASCII string representation, or the string
"<?>"
if none is available.
.SH "FILES"
These funtions are implemented in the file
\fIchars.c\fR.
.SH "SEE ALSO"
mandoc(1),
mandoc_escape(3),
mandoc_char(7),
roff(7)
.SH "HISTORY"
These functions and their predecessors have been available since the
following mandoc versions:
.TS
l l l l.
.PP
\fBfunction\fR	since	\fBpredecessor\fR	since
.PP
\fBmchars_alloc\fR()	1.11.3	\fBascii2htab\fR()	1.5.3
.PP
\fBmchars_free\fR()	1.11.2	\fBasciifree\fR()	1.6.0
.PP
\fBmchars_num2char\fR()	1.11.2	\fBchars_num2char\fR()	1.10.10
.PP
\fBmchars_num2uc\fR()	1.11.3	\(em	\(em
.PP
\fBmchars_spec2cp\fR()	1.11.2	\fBchars_spec2cp\fR()	1.10.5
.PP
\fBmchars_spec2str\fR()	1.11.2	\fBa2ascii\fR()	1.5.3
.PP
\fBmchars_uc2str\fR()	1.13.2	\(em	\(em
.TE
.SH "AUTHORS"
Kristaps Dzonsons <\fIkristaps@bsd.lv\fR>
.br
Ingo Schwarze <\fIschwarze@openbsd.org\fR>