.TH "caca_charset" 3caca "Mon Mar 25 2024 04:02:10" "Version 0.99.beta20" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_charset \- libcaca character set conversions
.SH SYNOPSIS
.br
.PP
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBlibcaca primitives drawing\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern uint32_t \fBcaca_utf8_to_utf32\fP (char const *, size_t *)"
.br
.RI "Convert a UTF-8 character to UTF-32\&. "
.ti -1c
.RI "__extern size_t \fBcaca_utf32_to_utf8\fP (char *, uint32_t)"
.br
.RI "Convert a UTF-32 character to UTF-8\&. "
.ti -1c
.RI "__extern uint8_t \fBcaca_utf32_to_cp437\fP (uint32_t)"
.br
.RI "Convert a UTF-32 character to CP437\&. "
.ti -1c
.RI "__extern uint32_t \fBcaca_cp437_to_utf32\fP (uint8_t)"
.br
.RI "Convert a CP437 character to UTF-32\&. "
.ti -1c
.RI "__extern char \fBcaca_utf32_to_ascii\fP (uint32_t)"
.br
.RI "Convert a UTF-32 character to ASCII\&. "
.ti -1c
.RI "__extern int \fBcaca_utf32_is_fullwidth\fP (uint32_t)"
.br
.RI "Tell whether a UTF-32 character is fullwidth\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions perform conversions between usual character sets\&. 
.SH "Function Documentation"
.PP 
.SS "__extern uint32_t caca_utf8_to_utf32 (char const * s, size_t * bytes)"
Convert a UTF-8 character read from a string and return its value in the UTF-32 character set\&. If the second argument is not null, the total number of read bytes is written in it\&.
.PP
If a null byte was reached before the expected end of the UTF-8 sequence, this function returns zero and the number of read bytes is set to zero\&.
.PP
This function never fails, but its behaviour with illegal UTF-8 sequences is undefined\&.
.PP
\fBParameters\fP
.RS 4
\fIs\fP A string containing the UTF-8 character\&. 
.br
\fIbytes\fP A pointer to a size_t to store the number of bytes in the character, or NULL\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The corresponding UTF-32 character, or zero if the character is incomplete\&. 
.RE
.PP

.PP
Referenced by \fBcaca_put_str()\fP\&.
.SS "__extern size_t caca_utf32_to_utf8 (char * buf, uint32_t ch)"
Convert a UTF-32 character read from a string and write its value in the UTF-8 character set into the given buffer\&.
.PP
This function never fails, but its behaviour with illegal UTF-32 characters is undefined\&.
.PP
\fBParameters\fP
.RS 4
\fIbuf\fP A pointer to a character buffer where the UTF-8 sequence will be written\&. 
.br
\fIch\fP The UTF-32 character\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of bytes written\&. 
.RE
.PP

.SS "__extern uint8_t caca_utf32_to_cp437 (uint32_t ch)"
Convert a UTF-32 character read from a string and return its value in the CP437 character set, or '?' if the character has no equivalent\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIch\fP The UTF-32 character\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The corresponding CP437 character, or '?' if not representable\&. 
.RE
.PP

.SS "__extern uint32_t caca_cp437_to_utf32 (uint8_t ch)"
Convert a CP437 character read from a string and return its value in the UTF-32 character set, or zero if the character is a CP437 control character\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIch\fP The CP437 character\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The corresponding UTF-32 character, or zero if not representable\&. 
.RE
.PP

.SS "__extern char caca_utf32_to_ascii (uint32_t ch)"
Convert a UTF-32 character into an ASCII character\&. When no equivalent exists, a graphically close equivalent is sought\&.
.PP
This function never fails, but its behaviour with illegal UTF-32 characters is undefined\&.
.PP
\fBParameters\fP
.RS 4
\fIch\fP The UTF-32 character\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The corresponding ASCII character, or a graphically close equivalent if found, or '?' if not representable\&. 
.RE
.PP

.SS "__extern int caca_utf32_is_fullwidth (uint32_t ch)"
Check whether the given UTF-32 character should be printed at twice the normal width (fullwidth characters)\&. If the character is unknown or if its status cannot be decided, it is treated as a standard-width character\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIch\fP The UTF-32 character\&. 
.RE
.PP
\fBReturns\fP
.RS 4
1 if the character is fullwidth, 0 otherwise\&. 
.RE
.PP

.PP
Referenced by \fBcaca_put_char()\fP, and \fBcaca_put_str()\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libcaca from the source code\&.