Add lsh man pages

Signed-off-by: Mattias Andrée <m@maandree.se>

2 files changed, 118 insertions, 18 deletions

diff --git a/libj2_j2i_lsh.3 b/libj2_j2i_lsh.3
new file mode 100644
index 0000000..70f0577
--- /dev/null
+++ b/libj2_j2i_lsh.3
@@ -0,0 +1,118 @@
+.TH LIBJ2_J2I_LSH 3 LIBJ2
+.SH NAME
+libj2_j2i_lsh \- Left-shift bits
+
+.SH SYNOPSIS
+.nf
+#include <libj2.h>
+
+void \fBlibj2_j2i_lsh\fP(struct libj2_j2i *\fIa\fP, unsigned \fIb\fP);
+void \fBlibj2_j2i_lsh_to_j2i\fP(const struct libj2_j2i *\fIa\fP, unsigned \fIb\fP, struct libj2_j2i *\fIr\fP);
+void \fBlibj2_ji_lsh_to_j2i\fP(intmax_t \fIa\fP, unsigned \fIb\fP, struct libj2_j2i *\fIr\fP);
+void \fBlibj2_j2u_lsh\fP(struct libj2_j2u *\fIa\fP, unsigned \fIb\fP);
+void \fBlibj2_j2u_lsh_to_j2u\fP(const struct libj2_j2u *\fIa\fP, unsigned \fIb\fP, struct libj2_j2u *\fIr\fP);
+void \fBlibj2_ju_lsh_to_j2u\fP(uintmax_t \fIa\fP, unsigned \fIb\fP, struct libj2_j2u *\fIr\fP);
+int \fBlibj2_j2i_lsh_overflow\fP(struct libj2_j2i *\fIa\fP, unsigned \fIb\fP);
+int \fBlibj2_j2i_lsh_to_j2i_overflow\fP(const struct libj2_j2i *\fIa\fP, unsigned \fIb\fP, struct libj2_j2i *\fIr\fP);
+int \fBlibj2_ji_lsh_to_j2i_overflow\fP(intmax_t \fIa\fP, unsigned \fIb\fP, struct libj2_j2i *\fIr\fP);
+int \fBlibj2_j2u_lsh_overflow\fP(struct libj2_j2u *\fIa\fP, unsigned \fIb\fP);
+int \fBlibj2_j2u_lsh_to_j2u_overflow\fP(const struct libj2_j2u *\fIa\fP, unsigned \fIb\fP, struct libj2_j2u *\fIr\fP);
+int \fBlibj2_ju_lsh_to_j2u_overflow\fP(uintmax_t \fIa\fP, unsigned \fIb\fP, struct libj2_j2u *\fIr\fP);
+int \fBlibj2_j2i_lsh_overflow_p\fP(const struct libj2_j2i *\fIa\fP, unsigned \fIb\fP);
+int \fBlibj2_ji_lsh_overflow_p\fP(intmax_t \fIa\fP, unsigned \fIb\fP);
+int \fBlibj2_j2u_lsh_overflow_p\fP(const struct libj2_j2u *\fIa\fP, unsigned \fIb\fP);
+int \fBlibj2_ju_lsh_overflow_p\fP(uintmax_t \fIa\fP, unsigned \fIb\fP);
+.fi
+.PP
+Link with
+.IR -lj2 .
+
+.SH DESCRIPTION
+The above listed functions discard the
+.I b
+most significant bits in
+.IR a ,
+shift all bits to
+.I b
+more significant positions, and clears the
+.I b
+least significant bits, effectively multiplying
+.I a
+by 2 to the power of
+.IR b .
+The functions with the parameter
+.I r
+store the result in
+.IR r ,
+the other functions store the result in
+.IR a ,
+except the functions
+.BR libj2_j2i_lsh_overflow_p (),
+.BR libj2_ji_lsh_overflow_p (),
+.BR libj2_j2u_lsh_overflow_p (),
+and
+.BR libj2_ju_lsh_overflow_p (),
+only predict overflow, and do not perform
+any bit-shifting, and therefore does store
+it anywhere.
+.PP
+The value-returning functions (that is, those
+with word
+.B overflow
+in their name), detect overflow, that is,
+if any discarded bit (any of the
+.I b
+most significant bits) was set.
+.PP
+The result is truncated to the least significant
+bits, as many as can be stored, in case of overflow;
+that is, modular arithmetics is used.
+
+.PP
+The arguments are assumed to be
+.RI non- NULL .
+
+.SH RETURN VALUE
+For functions with a return value, the functions
+return +1 if any discarded bit was set and
+.I a
+was positive, -1 if any discarded bit was set and
+.I a
+was negative,
+and 0 otherwise.
+
+.SH ERRORS
+The above listed functions cannot fail.
+
+.SH HISTORY
+The
+.BR libj2_j2u_lsh (),
+.BR libj2_j2u_lsh_to_j2u (),
+.BR libj2_ju_lsh_to_j2u (),
+.BR libj2_j2u_lsh_overflow (),
+.BR libj2_j2u_lsh_to_j2u_overflow (),
+.BR libj2_ju_lsh_to_j2u_overflow (),
+.BR libj2_j2u_lsh_overflow_p (),
+and
+.BR libj2_ju_lsh_overflow_p ()
+functions were added in version 1.0 of
+.BR libj2 .
+.PP
+The
+.BR libj2_j2i_lsh (),
+.BR libj2_j2i_lsh_to_j2i (),
+.BR libj2_ji_lsh_to_j2i (),
+.BR libj2_j2i_lsh_overflow (),
+.BR libj2_j2i_lsh_to_j2i_overflow (),
+.BR libj2_ji_lsh_to_j2i_overflow (),
+.BR libj2_j2i_lsh_overflow_p (),
+and
+.BR libj2_ji_lsh_overflow_p ()
+functions were added in version 1.1 of
+.BR libj2 .
+
+.SH SEE ALSO
+.BR libj2 (7),
+.BR libj2_j2i_rsh_j2i (3),
+.BR libj2_j2i_lrot_j2i (3),
+.BR libj2_j2i_rrot_j2i (3)
diff --git a/libj2_j2i_lsh.c b/libj2_j2i_lsh.c
index 8a00180..053ece7 100644
--- a/libj2_j2i_lsh.c
+++ b/libj2_j2i_lsh.c
@@ -3,24 +3,6 @@
 #ifndef TEST
 
 extern inline void libj2_j2i_lsh(struct libj2_j2i *a, unsigned b);
-/* TODO Add man pages
-   libj2_j2i_lsh
-   libj2_j2i_lsh_to_j2i
-   libj2_ji_lsh_to_j2i
-   libj2_j2u_lsh
-   libj2_j2u_lsh_to_j2u
-   libj2_ju_lsh_to_j2u
-   libj2_j2i_lsh_overflow
-   libj2_j2i_lsh_to_j2i_overflow
-   libj2_ji_lsh_to_j2i_overflow
-   libj2_j2u_lsh_overflow
-   libj2_j2u_lsh_to_j2u_overflow
-   libj2_ju_lsh_to_j2u_overflow
-   libj2_j2i_lsh_overflow_p
-   libj2_j2u_lsh_overflow_p
-   libj2_ji_lsh_overflow_p
-   libj2_ju_lsh_overflow_p
- */
 
 
 #else