head	1.10;
access;
symbols;
locks; strict;
comment	@# @;


1.10
date	2005.01.13.08.42.34;	author rse;	state Exp;
branches;
next	1.9;

1.9
date	2004.01.09.11.28.23;	author rse;	state Exp;
branches;
next	1.8;

1.8
date	2004.01.09.11.25.48;	author rse;	state Exp;
branches;
next	1.7;

1.7
date	2004.01.09.11.24.21;	author rse;	state Exp;
branches;
next	1.6;

1.6
date	2003.03.23.18.07.15;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	2002.06.26.16.00.25;	author rse;	state Exp;
branches;
next	1.4;

1.4
date	2002.04.28.19.04.00;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	2002.04.28.18.58.01;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	2002.04.28.13.27.24;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	2002.04.28.13.22.49;	author rse;	state Exp;
branches;
next	;


desc
@@


1.10
log
@happy new year 2005
@
text
@##
##  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

@


1.9
log
@OSSP ui64 was never done under C&W work time, so no need to give them the copyright
@
text
@d3 2
a4 2
##  Copyright (c) 2002-2004 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2004 The OSSP Project <http://www.ossp.org/>
@


1.8
log
@bump copyright for year 2004
@
text
@a4 1
##  Copyright (c) 2002-2004 Cable & Wireless Deutschland <http://www.cw.com/de/>
@


1.7
log
@strip trailing whitespaces
@
text
@d3 3
a5 3
##  Copyright (c) 2002-2003 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2003 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2003 Cable & Wireless Deutschland <http://www.cw.com/de/>
@


1.6
log
@bump copyright year
@
text
@d43 22
a64 22
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>.  
d147 1
a147 1
Addition of I<x> and I<y>. 
d157 1
a157 1
Subtraction of I<y> from I<x>. 
d167 1
a167 1
Multiplication of I<x> and I<y>. 
d177 1
a177 1
Division of I<x> by I<y>. 
@


1.5
log
@polishing
@
text
@d3 3
a5 3
##  Copyright (c) 2002 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
@


1.4
log
@describe ui64 is a little bit more detail
@
text
@d69 15
a83 4
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. The library does no dynamic memory allocations and instead passes
B<ui64_t> values directly through the API functions.
d95 1
a95 1
The value 0, expressed as an ui64_t.
d99 1
a99 1
The maximum value expressable as an ui64_t.
d153 1
a153 1
Same as B<ui64_add>, but I<y> and I<ov> are single digits to base 2^8.
d163 1
a163 1
Same as B<ui64_sub>, but I<y> and I<ov> are single digits to base 2^8.
d173 1
a173 1
Same as B<ui64_mul>, but I<y> and I<ov> are single digits to base 2^8.
d183 1
a183 1
Same as B<ui64_div>, but I<y> and I<ov> are single digits to base 2^8.
d227 1
a227 1
Number of digits (1-8) to base 2^8 in I<x>.
d238 1
a238 1
B<OSSP ui64> was invented in April 2002 by Ralf S. Engelschall
d241 3
a243 3
integers inside B<OSSP tai>. The core implementation is derived
from the B<XP> library in David R. Hanson's book C<C Interfaces and
Implementations>.
@


1.3
log
@first cut for a real documentation
@
text
@d69 4
@


1.2
log
@remember source of the core pieces
@
text
@d43 22
a64 1
...
d68 1
a68 1
B<OSSP ui64> is a ...
d70 1
a70 1
=head2 APPLICATION PROGRAMMER INTERFACE (API)
d72 1
a72 1
=head1 EXAMPLE
d74 1
a74 1
=head1 SEE ALSO
d76 144
a219 1
B<ISO-C> unsigned long long.
@


1.1
log
@Add first cut of OSSP ui64, a new (sub-)library which allows us to
perform 64-bit unsigned integer arithmetic in a portable way without
requiring the machine to support C99's 64-bit type "unsigned long long".
Basically a ui64_t is an 8 byte array of "unsigned char" elements and
hence the library internally stores 64-bit values as 8 digits to the
base 2^8 and also performs the mathematical operations this way.
@
text
@d62 3
a64 1
integers inside B<OSSP tai>.
@