.TH LIBJ2_J2I_TO_STR 3 LIBJ2
.SH NAME
libj2_j2i_to_str \- ASCII-encode a double-max precision integer

.SH SYNOPSIS
.nf
#include <libj2.h>

size_t \fBlibj2_j2i_to_str\fP(const struct libj2_j2i *\fIa\fP, char *\fIbuf\fP,
                        size_t \fIbufsize\fP, const char *\fIdigits\fP);

size_t \fBlibj2_j2u_to_str\fP(const struct libj2_j2u *\fIa\fP, char *\fIbuf\fP,
                        size_t \fIbufsize\fP, const char *\fIdigits\fP);
.fi
.PP
Link with
.IR -lj2 .

.SH DESCRIPTION
The
.BR libj2_j2i_to_str ()
and
.BR libj2_j2u_to_str ()
functions encode
.I a
in ASCII. The functions write up to
.IR bufsize ,
which may be 0, bytes, including a null
byte to termiante the encoding, to
.IR buf .
.PP
.I digits
shall either be
.I NULL
(equivalent to
.BR \(dq0123456789\(dq )
for the decimal system, or the digits to use
in order of value (zero first). The radix
will be the length of
.IR digits ,
which must be atleast 2.
.PP
The string encoding will not contain any leading
zeroes (if the value is zero, the string will be
a single zero). In the case of
.BR libj2_j2i_to_str (),
if
.I a
is negative, the ASCII minus sign
.RB ( - )
will be used as the prefix sign. No sign is used
for non-negative values.
.PP
If
.I bufsize
is non-zero but not large enough to fully encode
.I a,
.I buf[bufsize-1]
will be set to a null byte.
.PP
The functions assume that
.I a
is
.RI non- NULL .

.SH RETURN VALUE
The
.BR libj2_j2i_to_str ()
and
.BR libj2_j2u_to_str ()
functions return the number of bytes needed encode
.I a
with the radix determined by
.I digits
(10 if
.IR NULL ).
This count does not include the NUL byte at the end.

.SH ERRORS
The
.BR libj2_j2i_to_str ()
and
.BR libj2_j2u_to_str ()
functions will fail if
.I digits
is
.RI non- NULL
and contains less than 2 symbols or contain
duplicate symbols. However no error code is used,
instead the functions simply return 0.

.SH HISTORY
The
.BR libj2_j2i_to_str ()
and
.BR libj2_j2u_to_str ()
functions were added in version 1.1 of
.BR libj2 .

.SH NOTES
The return value is not affected by
.IR bufsize .

.SH SEE ALSO
.BR libj2 (7),
.BR libj2_str_to_j2i (3),
.BR libj2_ju_to_j2i (3)