##
##  OSSP ui64 - 64-Bit Arithmetic
##  Copyright (c) 2002-2005 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2002-2005 The OSSP Project <http://www.ossp.org/>
##
##  This file is part of OSSP ui64, a 64-bit arithmetic library
##  which can be found at http://www.ossp.org/pkg/lib/ui64/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  ui64.pod: library manual page
##

=pod

=head1 NAME

B<OSSP ui64> - 64-Bit Arithmetic

=head1 VERSION

B<OSSP ui64 UI64_VERSION_STR>

=head1 SYNOPSIS

B<ui64_zero>,
B<ui64_max>,
B<ui64_n2i>,
B<ui64_i2n>,
B<ui64_s2i>,
B<ui64_i2s>,
B<ui64_add>,
B<ui64_addn>,
B<ui64_sub>,
B<ui64_subn>,
B<ui64_mul>,
B<ui64_muln>,
B<ui64_div>,
B<ui64_divn>,
B<ui64_and>,
B<ui64_or>,
B<ui64_xor>,
B<ui64_not>,
B<ui64_rol>,
B<ui64_ror>,
B<ui64_len>,
B<ui64_cmp>.

=head1 DESCRIPTION

B<OSSP ui64> is a small B<ISO-C> library for portable 64-bit arithmetic.
It allows to perform the usual arithmetical and bit-wise operations on a
B<ISO-C> type B<ui64_t> which resembles a 64-bit unsigned integer type.

In contrast to a built-in C type like the C94 B<unsigned long> or even
the similar C99 B<unsigned long long>, the operations on B<ui64_t>
provide full support for correct carry/overflow semantics.

The library does no dynamic memory allocations at all and instead
passes B<ui64_t> objects by value within the API. This provides a very
convinient and low-overhead interface.

Internally, B<OSSP ui64> stores the B<ui64_t> in exactly (the expected)
8 octets which at any time hold the 64-bit value in a portable
I<8-digits-to-base-256> representation. Nevertheless the B<ui64_t> type
should be treated as an opaque type.

=head1 APPLICATION PROGRAMMER INTERFACE (API)

=head2 Particular Values

API functions providing particular values:

=over 4

=item ui64_t B<ui64_zero>(void);

The value 0, expressed as an B<ui64_t>.

=item ui64_t B<ui64_max>(void);

The maximum value expressable as an B<ui64_t>.

=back

=head2 Import & Export

API functions providing value importing and exporting to and from native
B<ISO-C> representations:

=over 4

=item ui64_t B<ui64_n2i>(unsigned long I<n>);

Import value from B<ISO-C> C<unsigned long> I<n>.

=item unsigned long B<ui64_i2n>(ui64_t I<x>);

Export value of I<x> to B<ISO-C> C<unsigned long>. This operation is not
less-less if the 64-bit value in I<x> exceeds the B<ISO-C> value
C<LONG_MAX>.

=item ui64_t B<ui64_s2i>(const char *I<str>, char **I<end>, int I<base>);

Import value from C<NUL>-terminated B<ISO-C> string representation
starting at I<str>. The representation can have leading whitespaces and
its (case-insensitive) digits (C<0>, ..., C<9>, C<A>, ..., C<Z>) are
interpreted to base I<base>. I<base> has to be greater or equal 2 and
less than 36. If I<end> is not C<NULL>, it is set to the first character
after the imported value representation.

=item char *B<ui64_i2s>(ui64_t I<x>, char *I<str>, size_t I<len>, int I<base>);

Export value of I<x> to B<ISO-C> string representation. The
representation consists of digits (C<0>, ..., C<9>, C<A>, ..., C<Z>) and
form the value to base I<base>. I<base> has to be greater or equal 2 and
less than 36. The representation is stored into the buffer starting at
I<str> and lasting I<len> bytes.

=back

=head2 Arithmetical Operations

API functions performing the standard arithmetical operations:

=over 4

=item ui64_t B<ui64_add>(ui64_t I<x>, ui64_t I<y>, ui64_t *I<ov>);

Addition of I<x> and I<y>.
If I<ov> is not C<NULL>, it receives the overflow value of
this operation (carry).

=item ui64_t B<ui64_addn>(ui64_t I<x>, int I<y>, int *I<ov>);

Same as B<ui64_add>, but I<y> and I<ov> are single digits to base 256.

=item ui64_t B<ui64_sub>(ui64_t I<x>, ui64_t I<y>, ui64_t *I<ov>);

Subtraction of I<y> from I<x>.
If I<ov> is not C<NULL>, it receives the overflow value of
this operation (borrow).

=item ui64_t B<ui64_subn>(ui64_t I<x>, int I<y>, int *I<ov>);

Same as B<ui64_sub>, but I<y> and I<ov> are single digits to base 256.

=item ui64_t B<ui64_mul>(ui64_t I<x>, ui64_t I<y>, ui64_t *I<ov>);

Multiplication of I<x> and I<y>.
If I<ov> is not C<NULL>, it receives the overflow value of
this operation).

=item ui64_t B<ui64_muln>(ui64_t I<x>, int I<y>, int *I<ov>);

Same as B<ui64_mul>, but I<y> and I<ov> are single digits to base 256.

=item ui64_t B<ui64_div>(ui64_t I<x>, ui64_t I<y>, ui64_t *I<ov>);

Division of I<x> by I<y>.
If I<ov> is not C<NULL>, it receives the overflow value of
this operation (remainder).

=item ui64_t B<ui64_divn>(ui64_t I<x>, int I<y>, int *I<ov>);

Same as B<ui64_div>, but I<y> and I<ov> are single digits to base 256.

=back

=head2 Bit Operations

API functions performing the standard bit-wise operations:

=over 4

=item ui64_t B<ui64_and>(ui64_t I<x>, ui64_t I<y>);

Bit-wise I<AND> operation between I<x> and I<y>.

=item ui64_t B<ui64_or>(ui64_t I<x>, ui64_t I<y>);

Bit-wise I<OR> operation between I<x> and I<y>.

=item ui64_t B<ui64_xor>(ui64_t I<x>, ui64_t I<y>);

Bit-wise I<Exclusive-OR> operation between I<x> and I<y>.

=item ui64_t B<ui64_not>(ui64_t I<x>);

Bit-wise I<NOT> operation of I<x>.

=item ui64_t B<ui64_rol>(ui64_t I<x>, int I<s>, ui64_t *I<ov>);

Bit-wise I<Rotate-Left> operation by I<s> bits of I<x>.
If I<ov> is not C<NULL>, it contains the out-rotated bits.

=item ui64_t B<ui64_ror>(ui64_t I<x>, int I<s>, ui64_t *I<ov>);

Bit-wise I<Rotate-Right> operation by I<s> bits of I<x>.
If I<ov> is not C<NULL>, it contains the out-rotated bits.

=back

=head2 Other Operations

=over 4

=item int B<ui64_len>(ui64_t I<x>);

Number of digits (1-8) to base 256 in I<x>.

=item int B<ui64_cmp>(ui64_t I<x>, ui64_t I<y>);

Comparison of I<x> and I<y> values. Returns C<-1>, C<0>
or C<+1> if I<x> is less/equal/greater than I<y>.

=back

=head1 HISTORY

B<OSSP ui64> was invented in April 2002 by I<Ralf S. Engelschall>
E<lt>rse@engelschall.comE<gt> for use inside the B<OSSP> project. Its
creation was prompted by the requirement to calculate with 64-bit
integers inside B<OSSP tai>, a time calculation library. The core
implementation is derived from the B<XP> library in I<David R. Hanson>'s
book I<C Interfaces and Implementations>.

=head1 AUTHORS

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut