.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);

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_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);

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_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_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);

void \fBlibj2_j2i_sat_lsh\fP(struct libj2_j2i *\fIa\fP, unsigned \fIb\fP);
void \fBlibj2_j2i_sat_lsh_to_j2i\fP(const struct libj2_j2i *\fIa\fP, unsigned \fIb\fP, struct libj2_j2i *\fIr\fP);
void \fBlibj2_ji_sat_lsh_to_j2i\fP(intmax_t \fIa\fP, unsigned \fIb\fP, struct libj2_j2i *\fIr\fP);

void \fBlibj2_j2u_sat_lsh\fP(struct libj2_j2u *\fIa\fP, unsigned \fIb\fP);
void \fBlibj2_j2u_sat_lsh_to_j2u\fP(const struct libj2_j2u *\fIa\fP, unsigned \fIb\fP, struct libj2_j2u *\fIr\fP);
void \fBlibj2_ju_sat_lsh_to_j2u\fP(uintmax_t \fIa\fP, unsigned \fIb\fP, struct libj2_j2u *\fIr\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
For the functions where
.I a
is a
.B uintmax_t
it is convert to a
.BR "struct libj2_j2u *" ,
and for the functions where
.I a
is a
.B intmax_t
it is convert to a
.BR "struct libj2_j2i *" ,
before described operations.
.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
.BR sat_lsh -functions
use saturated arithmetics, meaning that the result
will be the maximum representable value on positive
overflow and the minimum representable value on
negative overflow.
.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 cleared 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 (),
.BR libj2_ji_lsh_overflow_p (),
.BR libj2_j2i_sat_lsh (),
.BR libj2_j2i_sat_lsh_to_j2i (),
.BR libj2_ji_sat_lsh_to_j2i (),
.BR libj2_j2u_sat_lsh (),
.BR libj2_j2u_sat_lsh_to_j2u (),
and
.BR libj2_ju_sat_lsh_to_j2u ()
functions were added in version 1.1 of
.BR libj2 .

.SH SEE ALSO
.BR libj2 (7),
.BR libj2_j2i_rsh (3),
.BR libj2_j2u_lrot (3),
.BR libj2_j2u_rrot (3)