1 files changed, 107 insertions, 0 deletions
diff --git a/libj2_j2i_to_str.3 b/libj2_j2i_to_str.3
new file mode 100644
index 0000000..ed64ab8
--- /dev/null
+++ b/libj2_j2i_to_str.3
@@ -0,0 +1,107 @@
+.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)