--- ui64.pod 2002/04/28 13:27:24 1.2
+++ ui64.pod 2002/04/28 18:58:01 1.3
@@ -40,19 +40,183 @@
=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 ...
+B<OSSP ui64> is a small B<ISO-C> library for portable 64-bit arithmetic.
-=head2 APPLICATION PROGRAMMER INTERFACE (API)
+=head1 APPLICATION PROGRAMMER INTERFACE (API)
-=head1 EXAMPLE
+=head2 Particular Values
-=head1 SEE ALSO
+API functions providing particular values:
-B<ISO-C> unsigned long long.
+=over 4
+
+=item ui64_t B<ui64_zero>(void);
+
+The value 0, expressed as an ui64_t.
+
+=item ui64_t B<ui64_max>(void);
+
+The maximum value expressable as an 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 2^8.
+
+=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 2^8.
+
+=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 2^8.
+
+=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 2^8.
+
+=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 2^8 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
|
