.TH "ggidev-add_3" 3 "2006-12-30" "libggi-2.2.x" GGI
.SH NAME
\fBggidev-add_3\fR, \fBggidev-sub_3\fR, \fBggidev-mul_3\fR, \fBggidev-divmod_3\fR : Binary arithmetic triple-int operations
.SH SYNOPSIS
.nb
.nf
#include <ggi/internal/triple-int.h>

unsigned *add_3(unsigned l[3], unsigned r[3]);
unsigned *sub_3(unsigned l[3], unsigned r[3]);

unsigned *mul_3(unsigned l[3], unsigned r[3]);
unsigned *divmod_3(unsigned a[3], unsigned b[3],
      unsigned q[3], unsigned r[3]);
.fi

.SH DESCRIPTION
\fBadd_3\fR adds \fBr\fR to \fBl\fR. Equivalent to l+=r.

\fBsub_3\fR subtracts \fBr\fR from \fBl\fR. Equivalent to l-=r.

\fBmul_3\fR multiplies \fBr\fR with \fBl\fR. Equivalent to l*=r.

\fBdivmod_3\fR calculates the quotient \fBq\fR and the remainder \fBr\fR of \fBa\fR/\fBb\fR
such that \fBa\fR = \fBq\fR * \fBb\fR + \fBr\fR. Equivalent to r=a%b,q=a/b.

Multiplication and division needs to operate on \fBlimbs\fR to perform long
multiplication and division. If a type with twice the precision of an
\fBunsigned\fR is found (typically the \fBlong long\fR type), \fBunsigned\fR is used
as the \fBlimb\fR. If not, half the bits of an \fBunsigned\fR are used as the
\fBlimb\fR.

The division algorithm is probably similar to the algorithm described
by Donald E. Knuth in "The Art of Computer Programming", volume 2, but
the author of the code has not actually read that book, only a short
description of the algorithm. The degree of similarity is therefore
uncertain.
.SH RETURN VALUE
\fBadd_3\fR, \fBsub_3\fR and \fBmul_3\fR all return a pointer to \fBl\fR which has
been updated in place.

'divmod_3` returns a pointer to the quotient \fBq\fR.
.SH EXAMPLES
Some binary arithmetic operations on \fBtriple-ints\fR:

.nb
.nf
unsigned x[3], y[3], q[3], r[3];

assign_int_3(x, 4);
assign_int_3(y, 5);
add_3(x, y);          /* x == 9 */
assign_int_3(q, 3);
sub_3(x, q);          /* x == 6 */
mul_3(x, q);          /* x == 18 */
divmod_3(x, y, q, r); /* q == 3, r == 3 */
.fi

.SH SEE ALSO
\f(CWtriple-int(7)\fR, \f(CWassign_int_3(3)\fR