ossp-pkg/ui64/ui64.pod
##
## 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
