diff options
Diffstat (limited to '')
| -rw-r--r-- | libj2_j2i_mul_j2i.3 | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/libj2_j2i_mul_j2i.3 b/libj2_j2i_mul_j2i.3 new file mode 100644 index 0000000..b0fb217 --- /dev/null +++ b/libj2_j2i_mul_j2i.3 @@ -0,0 +1,276 @@ +.TH LIBJ2_J2I_MUL_J2I 3 LIBJ2 +.SH NAME +libj2_j2i_mul_j2i \- Calculate product + +.SH SYNOPSIS +.nf +#include <libj2.h> + +enum libj2_overflow { + \fILIBJ2_NO_OVERFLOW\fP = 0, + \fILIBJ2_POSITIVE_OVERFLOW\fP = 1, + \fILIBJ2_POSITIVE_OVERFLOW_UNKNOWN\fP = 2, + \fILIBJ2_NEGATIVE_OVERFLOW\fP = -1, + \fILIBJ2_NEGATIVE_OVERFLOW_UNKNOWN\fP = -2 +}; + +#define \fILIBJ2_OVERFLOW\fP LIBJ2_POSITIVE_OVERFLOW +#define \fILIBJ2_OVERFLOW_UNKNOWN\fP LIBJ2_POSITIVE_OVERFLOW_UNKNOWN + +void \fBlibj2_j2i_mul_j2i\fP(struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP); +void \fBlibj2_j2i_mul_j2i_to_j2i\fP(const struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP, struct libj2_j2i *\fIr\fP); +void \fBlibj2_j2i_mul_ji\fP(struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP); +void \fBlibj2_j2i_mul_ji_to_j2i\fP(const struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP, struct libj2_j2i *\fIr\fP); +void \fBlibj2_ji_mul_j2i_to_j2i\fP(intmax_t \fIa\fP, const struct libj2_j2i *\fIb\fP, struct libj2_j2i *\fIr\fP); +void \fBlibj2_ji_mul_ji_to_j2i\fP(intmax_t \fIa\fP, intmax_t \fIb\fP, struct libj2_j2i *\fIr\fP); + +int \fBlibj2_j2i_mul_j2i_overflow\fP(struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP); +int \fBlibj2_j2i_mul_j2i_to_j2i_overflow\fP(const struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP, struct libj2_j2i *\fIr\fP); +int \fBlibj2_j2i_mul_ji_overflow\fP(struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP); +int \fBlibj2_j2i_mul_ji_to_j2i_overflow\fP(const struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP, struct libj2_j2i *\fIr\fP); +int \fBlibj2_ji_mul_j2i_to_j2i_overflow\fP(intmax_t \fIa\fP, const struct libj2_j2i *\fIb\fP, struct libj2_j2i *\fIr\fP); + +int \fBlibj2_j2i_mul_j2i_overflow_p\fP(const struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP); +int \fBlibj2_j2i_mul_ji_overflow_p\fP(const struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP); +int \fBlibj2_ji_mul_j2i_overflow_p\fP(intmax_t \fIa\fP, const struct libj2_j2i *\fIb\fP); + +enum libj2_overflow \fBlibj2_j2i_mul_j2i_overflow_p_quick\fP(const struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP); +enum libj2_overflow \fBlibj2_j2i_mul_ji_overflow_p_quick\fP(const struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP); +enum libj2_overflow \fBlibj2_ji_mul_j2i_overflow_p_quick\fP(intmax_t \fIa\fP, const struct libj2_j2i *\fIb\fP); + +int \fBlibj2_j2i_mul_j2i_to_j2i_overflow_p\fP(const struct libj2_j2i *\fIa\fP, const struct libj2_j2i *\fIb\fP, struct libj2_j2i *\fIr\fP, int *\fIr_set\fP); +int \fBlibj2_j2i_mul_ji_to_j2i_overflow_p\fP(const struct libj2_j2i *\fIa\fP, intmax_t \fIb\fP, struct libj2_j2i *\fIr\fP, int *\fIr_set\fP); +int \fBlibj2_ji_mul_j2i_to_j2i_overflow_p\fP(intmax_t \fIa\fP, const struct libj2_j2i *\fIb\fP, struct libj2_j2i *\fIr\fP, int *\fIr_set\fP); + +void \fBlibj2_j2u_mul_j2u\fP(struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP); +void \fBlibj2_j2u_mul_j2u_to_j2u\fP(const struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP, struct libj2_j2u *\fIr\fP); +void \fBlibj2_j2u_mul_ju\fP(struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP); +void \fBlibj2_j2u_mul_ju_to_j2u\fP(const struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP, struct libj2_j2u *\fIr\fP); +void \fBlibj2_ju_mul_j2u_to_j2u\fP(uintmax_t \fIa\fP, const struct libj2_j2u *\fIb\fP, struct libj2_j2u *\fIr\fP); +void \fBlibj2_ju_mul_ju_to_j2u\fP(uintmax_t \fIa\fP, uintmax_t \fIb\fP, struct libj2_j2u *\fIr\fP); +void \fBlibj2_j2u_mul_j2u_destructive\fP(struct libj2_j2u *restrict \fIa\fP, struct libj2_j2u *restrict \fIb\fP); + +int \fBlibj2_j2u_mul_j2u_overflow\fP(struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP); +int \fBlibj2_j2u_mul_j2u_to_j2u_overflow\fP(const struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP, struct libj2_j2u *\fIr\fP); +int \fBlibj2_j2u_mul_ju_overflow\fP(struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP); +int \fBlibj2_j2u_mul_ju_to_j2u_overflow\fP(const struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP, struct libj2_j2u *\fIr\fP); +int \fBlibj2_ju_mul_j2u_to_j2u_overflow\fP(uintmax_t \fIa\fP, const struct libj2_j2u *\fIb\fP, struct libj2_j2u *\fIr\fP); +int \fBlibj2_j2u_mul_j2u_overflow_destructive\fP(struct libj2_j2u *restrict \fIa\fP, struct libj2_j2u *restrict \fIb\fP); + +int \fBlibj2_j2u_mul_j2u_overflow_p\fP(const struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP); +int \fBlibj2_j2u_mul_ju_overflow_p\fP(const struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP); +int \fBlibj2_ju_mul_j2u_overflow_p\fP(uintmax_t \fIa\fP, const struct libj2_j2u *\fIb\fP); + +enum libj2_overflow \fBlibj2_j2u_mul_j2u_overflow_p_quick\fP(const struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP); +enum libj2_overflow \fBlibj2_j2u_mul_ju_overflow_p_quick\fP(const struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP); +enum libj2_overflow \fBlibj2_ju_mul_j2u_overflow_p_quick\fP(uintmax_t \fIa\fP, const struct libj2_j2u *\fIb\fP); + +int \fBlibj2_j2u_mul_j2u_to_j2u_overflow_p\fP(const struct libj2_j2u *\fIa\fP, const struct libj2_j2u *\fIb\fP, struct libj2_j2u *\fIr\fP, int *\fIr_set\fP); +int \fBlibj2_j2u_mul_ju_to_j2u_overflow_p\fP(const struct libj2_j2u *\fIa\fP, uintmax_t \fIb\fP, struct libj2_j2u *\fIr\fP, int *\fIr_set\fP); +int \fBlibj2_ju_mul_j2u_to_j2u_overflow_p\fP(uintmax_t \fIa\fP, const struct libj2_j2u *\fIb\fP, struct libj2_j2u *\fIr\fP, int *\fIr_set\fP); +.fi +.PP +Link with +.IR -lj2 . + +.SH DESCRIPTION +The above listed functions calculate the +product of the values of +.I a +and +.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_mul_j2i_overflow_p (), +.BR libj2_j2i_mul_ji_overflow_p (), +.BR libj2_ji_mul_j2i_overflow_p (), +.BR libj2_j2u_mul_j2u_overflow_p (), +.BR libj2_j2u_mul_ju_overflow_p (), +.BR libj2_ju_mul_j2u_overflow_p (), +.BR libj2_j2i_mul_j2i_overflow_p_quick (), +.BR libj2_j2i_mul_ji_overflow_p_quick (), +.BR libj2_ji_mul_j2i_overflow_p_quick (), +.BR libj2_j2u_mul_j2u_overflow_p_quick (), +.BR libj2_j2u_mul_ju_overflow_p_quick (), +and +.BR libj2_ju_mul_j2u_overflow_p_quick () +only predict overflow, and do not calculate +the sum, and therefore does store it anywhere. +.PP +Additionally, in situations where the +.BR libj2_j2i_mul_j2i_overflow_p_quick (), +.BR libj2_j2i_mul_ji_overflow_p_quick (), +.BR libj2_ji_mul_j2i_overflow_p_quick (), +.BR libj2_j2u_mul_j2u_overflow_p_quick (), +.BR libj2_j2u_mul_ju_overflow_p_quick (), +and +.BR libj2_ju_mul_j2u_overflow_p_quick () +functions return +.I LIBJ2_POSITIVE_OVERFLOW_UNKNOWN +or +.IR LIBJ2_NEGATIVE_OVERFLOW_UNKNOWN , +the +.BR libj2_j2i_mul_j2i_to_j2i_overflow_p () +.BR libj2_j2i_mul_ji_to_j2i_overflow_p () +.BR libj2_ji_mul_j2i_to_j2i_overflow_p () +.BR libj2_j2u_mul_j2u_to_j2u_overflow_p () +.BR libj2_j2u_mul_ju_to_j2u_overflow_p (), +and +.BR libj2_ju_mul_j2u_to_j2u_overflow_p () +functions will calculate the product, store it in +.I r +and set +.I *r_set +to 1; in other situations, those functions will +not modify +.I r +but will set +.I *r_set +to 0. +.PP +The value-returning functions (that is, those +with word +.B overflow +in their name), detect arithmetic overflow. +.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 +.BR libj2_j2u_mul_j2u_destructive () +and +.BR libj2_j2u_mul_j2u_overflow_destructive () +functions modifies +.I b +arbitrarily, and do not support +.I a +and +.I b +being the same pointer. +.PP +The arguments are assumed to be +.RI non- NULL . + +.SH RETURN VALUE +For functions with a return value, the functions +return +1 if the result is positive but too large +to be represented, -1 if the result is negative +(not only possible with functions where the result is a +.IR "struct libj2_j2i" ) +but too large, and 0 otherwise. +For the +.BR libj2_j2i_mul_j2i_overflow_p_quick (), +.BR libj2_j2i_mul_ji_overflow_p_quick (), +.BR libj2_ji_mul_j2i_overflow_p_quick (), +.BR libj2_j2u_mul_j2u_overflow_p_quick (), +.BR libj2_j2u_mul_ju_overflow_p_quick (), +and +.BR libj2_ju_mul_j2u_overflow_p_quick () +functions, the return value is a +.BR "enum libj2_overflow" , +which may be unsigned, so to check if the +return value was negative, it is best to +first cast it to an integer, or compare it +directly to the negative constants. Additionally, +these functions will return +.I LIBJ2_POSITIVE_OVERFLOW_UNKNOWN +if the result is positive but if could not +be determined without calculating the +product whether the product is too large to +be represented, and +.I LIBJ2_NEGATIVE_OVERFLOW_UNKNOWN +if the result is negative but if could not +be determined without calculating the +product whether the product is too large to +be represented. +.PP +Since the +.BR libj2_j2u_mul_j2u_overflow_p_quick (), +.BR libj2_j2u_mul_ju_overflow_p_quick (), +and +.BR libj2_ju_mul_j2u_overflow_p_quick () +functions operate on unsigned integers, they +will never return +.I LIBJ2_NEGATIVE_OVERFLOW +or +.IR LIBJ2_NEGATIVE_OVERFLOW_UNKNOWN . + +.SH ERRORS +The above listed functions cannot fail. + +.SH HISTORY +The +.BR libj2_j2u_mul_j2u (), +.BR libj2_j2u_mul_j2u_to_j2u (), +.BR libj2_j2u_mul_ju (), +.BR libj2_j2u_mul_ju_to_j2u (), +.BR libj2_ju_mul_j2u_to_j2u (), +.BR libj2_ju_mul_ju_to_j2u (), +.BR libj2_j2u_mul_j2u_destructive (), +.BR libj2_j2u_mul_j2u_overflow (), +.BR libj2_j2u_mul_j2u_to_j2u_overflow (), +.BR libj2_j2u_mul_ju_overflow (), +.BR libj2_j2u_mul_ju_to_j2u_overflow (), +.BR libj2_ju_mul_j2u_to_j2u_overflow (), +.BR libj2_j2u_mul_j2u_overflow_destructive (), +.BR libj2_j2u_mul_j2u_overflow_p (), +.BR libj2_j2u_mul_ju_overflow_p (), +.BR libj2_ju_mul_j2u_overflow_p (), +.BR libj2_j2u_mul_j2u_overflow_p_quick (), +.BR libj2_j2u_mul_ju_overflow_p_quick (), +.BR libj2_ju_mul_j2u_overflow_p_quick (), +.BR libj2_j2u_mul_j2u_to_j2u_overflow_p (), +.BR libj2_j2u_mul_ju_to_j2u_overflow_p (), +and +.BR libj2_ju_mul_j2u_to_j2u_overflow_p () +functions and the +.IR LIBJ2_NO_OVERFLOW , +.IR LIBJ2_OVERFLOW , +and +.IR LIBJ2_OVERFLOW_UNKNOWN +constants were added in version 1.0 of +.BR libj2 . +.PP +The +.BR libj2_j2i_mul_j2i (), +.BR libj2_j2i_mul_j2i_to_j2i (), +.BR libj2_j2i_mul_ji (), +.BR libj2_j2i_mul_ji_to_j2i (), +.BR libj2_ji_mul_j2i_to_j2i (), +.BR libj2_ji_mul_ji_to_j2i (), +.BR libj2_j2i_mul_j2i_overflow (), +.BR libj2_j2i_mul_j2i_to_j2i_overflow (), +.BR libj2_j2i_mul_ji_overflow (), +.BR libj2_j2i_mul_ji_to_j2i_overflow (), +.BR libj2_ji_mul_j2i_to_j2i_overflow (), +.BR libj2_j2i_mul_j2i_overflow_p (), +.BR libj2_j2i_mul_ji_overflow_p (), +.BR libj2_ji_mul_j2i_overflow_p (), +.BR libj2_j2i_mul_j2i_overflow_p_quick (), +.BR libj2_j2i_mul_ji_overflow_p_quick (), +.BR libj2_ji_mul_j2i_overflow_p_quick (), +.BR libj2_j2i_mul_j2i_to_j2i_overflow_p (), +.BR libj2_j2i_mul_ji_to_j2i_overflow_p (), +and +.BR libj2_ji_mul_j2i_to_j2i_overflow_p () +functions and the +.IR LIBJ2_POSITIVE_OVERFLOW , +.IR LIBJ2_POSITIVE_OVERFLOW_UNKNOWN , +.IR LIBJ2_NEGATIVE_OVERFLOW , +and +.IR LIBJ2_NEGATIVE_OVERFLOW_UNKNOWN +constants were added in version 1.1 of +.BR libj2 . + +.SH SEE ALSO +.BR libj2 (7), +.BR libj2_j2i_add_j2i (3), +.BR libj2_j2i_sub_j2i (3), +.BR libj2_j2u_sub_j2u (3), +.BR libj2_j2i_divmod_j2i (3) |