<commit_before>=head1 Introduction

C<isl> is a thread-safe C library for manipulating
sets and relations of integer points bounded by affine constraints.
The descriptions of the sets and relations may involve
both parameters and existentially quantified variables.
All computations are performed in exact integer arithmetic
using C<GMP>.
The C<isl> library offers functionality that is similar
to that offered by the C<Omega> and C<Omega+> libraries,
but the underlying algorithms are in most cases completely different.

The library is by no means complete and some fairly basic
functionality is still missing.
Still, even in its current form, the library has been successfully
used as a backend polyhedral library for the polyhedral
scanner C<CLooG> and as part of an equivalence checker of
static affine programs.

=head1 Installation

The source of C<isl> can be obtained either as a tarball
or from the git repository.  Both are available from
L<http://freshmeat.net/projects/isl/>.
The installation process depends on how you obtained
the source.

=head2 Installation from the git repository

=over

=item 1 Clone or update the repository

The first time the source is obtained, you need to clone
the repository.

	git clone git://repo.or.cz/isl.git

To obtain updates, you need to pull in the latest changes

	git pull

=item 2 Get submodule (optional)

C<isl> can optionally use the C<piplib> library and provides
this library as a submodule.  If you want to use it, then
after you have cloned C<isl>, you need to grab the submodules

	git submodule init
	git submodule update

To obtain updates, you only need

	git submodule update

Note that C<isl> currently does not use any C<piplib>
functionality by default.

=item 3 Generate C<configure>

	./autogen.sh

=back

After performing the above steps, continue
with the L<Common installation instructions>.

=head2 Common installation instructions

=over

=item 1 Obtain C<GMP>

Building C<isl> requires C<GMP>, including its headers files.
Your distribution may not provide these header files by default
and you may need to install a package called C<gmp-devel> or something
similar.  Alternatively, C<GMP> can be built from
source, available from L<http://gmplib.org/>.

=item 2 Configure

C<isl> uses the standard C<autoconf> C<configure> script.
To run it, just type

	./configure

optionally followed by some configure options.
A complete list of options can be obtained by running

	./configure --help

Below we discuss some of the more common options.

C<isl> can optionally use C<piplib>, but no
C<piplib> functionality is currently used by default.
The C<--with-piplib> option can
be used to specify which C<piplib>
library to use, either an installed version (C<system>),
an externally built version (C<build>), a bundled version (C<bundled>)
or no version (C<no>).  The option C<build> is mostly useful
in C<configure> scripts of larger projects that bundle both C<isl>
and C<piplib>.

=over

=item C<--prefix>

Installation prefix for C<isl>

=item C<--with-gmp-prefix>

Installation prefix for C<GMP> (architecture-independent files).

=item C<--with-gmp-exec-prefix>

Installation prefix for C<GMP> (architecture-dependent files).

=item C<--with-piplib>

Which copy of C<piplib> to use, either C<no> (default), C<system>, C<build>
or C<bundled>.  Note that C<bundled> only works if you have obtained
C<isl> and its submodules from the git repository.

=item C<--with-piplib-prefix>

Installation prefix for C<system> C<piplib> (architecture-independent files).

=item C<--with-piplib-exec-prefix>

Installation prefix for C<system> C<piplib> (architecture-dependent files).

=item C<--with-piplib-builddir>

Location where C<build> C<piplib> was built.

=back

=item 3 Compile

	make

=item 4 Install (optional)

	make install

=back

=head1 Library

=head2 Initialization

All manipulations of integer sets and relations occur within
the context of an C<isl_ctx>.
A given C<isl_ctx> can only be used within a single thread.
All arguments of a function are required to have been allocated
within the same context.
There are currently no functions available for moving an object
from one C<isl_ctx> to another C<isl_ctx>.  This means that
there is currently no way of safely moving an object from one
thread to another, unless the whole C<isl_ctx> is moved.

An C<isl_ctx> can be allocated using C<isl_ctx_alloc> and
freed using C<isl_ctx_free>.
All objects allocated within an C<isl_ctx> should be freed
before the C<isl_ctx> itself is freed.

	isl_ctx *isl_ctx_alloc();
	void isl_ctx_free(isl_ctx *ctx);

=head2 Integers

All operations on integers, mainly the coefficients
of the constraints describing the sets and relations,
are performed in exact integer arithmetic using C<GMP>.
However, to allow future versions of C<isl> to optionally
support fixed integer arithmetic, all calls to C<GMP>
are wrapped inside C<isl> specific macros.
The basic type is C<isl_int> and the following operations
are available on this type.

=over

=item isl_int_init(i)

=item isl_int_clear(i)

=item isl_int_set(r,i)

=item isl_int_set_si(r,i)

=item isl_int_abs(r,i)

=item isl_int_neg(r,i)

=item isl_int_swap(i,j)

=item isl_int_swap_or_set(i,j)

=item isl_int_add_ui(r,i,j)

=item isl_int_sub_ui(r,i,j)

=item isl_int_add(r,i,j)

=item isl_int_sub(r,i,j)<commit_msg>doc: a bit more on integers<commit_after>=head1 Introduction

C<isl> is a thread-safe C library for manipulating
sets and relations of integer points bounded by affine constraints.
The descriptions of the sets and relations may involve
both parameters and existentially quantified variables.
All computations are performed in exact integer arithmetic
using C<GMP>.
The C<isl> library offers functionality that is similar
to that offered by the C<Omega> and C<Omega+> libraries,
but the underlying algorithms are in most cases completely different.

The library is by no means complete and some fairly basic
functionality is still missing.
Still, even in its current form, the library has been successfully
used as a backend polyhedral library for the polyhedral
scanner C<CLooG> and as part of an equivalence checker of
static affine programs.

=head1 Installation

The source of C<isl> can be obtained either as a tarball
or from the git repository.  Both are available from
L<http://freshmeat.net/projects/isl/>.
The installation process depends on how you obtained
the source.

=head2 Installation from the git repository

=over

=item 1 Clone or update the repository

The first time the source is obtained, you need to clone
the repository.

	git clone git://repo.or.cz/isl.git

To obtain updates, you need to pull in the latest changes

	git pull

=item 2 Get submodule (optional)

C<isl> can optionally use the C<piplib> library and provides
this library as a submodule.  If you want to use it, then
after you have cloned C<isl>, you need to grab the submodules

	git submodule init
	git submodule update

To obtain updates, you only need

	git submodule update

Note that C<isl> currently does not use any C<piplib>
functionality by default.

=item 3 Generate C<configure>

	./autogen.sh

=back

After performing the above steps, continue
with the L<Common installation instructions>.

=head2 Common installation instructions

=over

=item 1 Obtain C<GMP>

Building C<isl> requires C<GMP>, including its headers files.
Your distribution may not provide these header files by default
and you may need to install a package called C<gmp-devel> or something
similar.  Alternatively, C<GMP> can be built from
source, available from L<http://gmplib.org/>.

=item 2 Configure

C<isl> uses the standard C<autoconf> C<configure> script.
To run it, just type

	./configure

optionally followed by some configure options.
A complete list of options can be obtained by running

	./configure --help

Below we discuss some of the more common options.

C<isl> can optionally use C<piplib>, but no
C<piplib> functionality is currently used by default.
The C<--with-piplib> option can
be used to specify which C<piplib>
library to use, either an installed version (C<system>),
an externally built version (C<build>), a bundled version (C<bundled>)
or no version (C<no>).  The option C<build> is mostly useful
in C<configure> scripts of larger projects that bundle both C<isl>
and C<piplib>.

=over

=item C<--prefix>

Installation prefix for C<isl>

=item C<--with-gmp-prefix>

Installation prefix for C<GMP> (architecture-independent files).

=item C<--with-gmp-exec-prefix>

Installation prefix for C<GMP> (architecture-dependent files).

=item C<--with-piplib>

Which copy of C<piplib> to use, either C<no> (default), C<system>, C<build>
or C<bundled>.  Note that C<bundled> only works if you have obtained
C<isl> and its submodules from the git repository.

=item C<--with-piplib-prefix>

Installation prefix for C<system> C<piplib> (architecture-independent files).

=item C<--with-piplib-exec-prefix>

Installation prefix for C<system> C<piplib> (architecture-dependent files).

=item C<--with-piplib-builddir>

Location where C<build> C<piplib> was built.

=back

=item 3 Compile

	make

=item 4 Install (optional)

	make install

=back

=head1 Library

=head2 Initialization

All manipulations of integer sets and relations occur within
the context of an C<isl_ctx>.
A given C<isl_ctx> can only be used within a single thread.
All arguments of a function are required to have been allocated
within the same context.
There are currently no functions available for moving an object
from one C<isl_ctx> to another C<isl_ctx>.  This means that
there is currently no way of safely moving an object from one
thread to another, unless the whole C<isl_ctx> is moved.

An C<isl_ctx> can be allocated using C<isl_ctx_alloc> and
freed using C<isl_ctx_free>.
All objects allocated within an C<isl_ctx> should be freed
before the C<isl_ctx> itself is freed.

	isl_ctx *isl_ctx_alloc();
	void isl_ctx_free(isl_ctx *ctx);

=head2 Integers

All operations on integers, mainly the coefficients
of the constraints describing the sets and relations,
are performed in exact integer arithmetic using C<GMP>.
However, to allow future versions of C<isl> to optionally
support fixed integer arithmetic, all calls to C<GMP>
are wrapped inside C<isl> specific macros.
The basic type is C<isl_int> and the following operations
are available on this type.
The meanings of these operations are essentially the same
as their C<GMP> C<mpz_> counterparts.
As always with C<GMP> types, C<isl_int>s need to be
initialized with C<isl_int_init> before they can be used
and they need to be released with C<isl_int_clear>
after the last use.

=over

=item isl_int_init(i)

=item isl_int_clear(i)

=item isl_int_set(r,i)

=item isl_int_set_si(r,i)

=item isl_int_abs(r,i)

=item isl_int_neg(r,i)

=item isl_int_swap(i,j)

=item isl_int_swap_or_set(i,j)

=item isl_int_add_ui(r,i,j)

=item isl_int_sub_ui(r,i,j)

=item isl_int_add(r,i,j)

=item isl_int_sub(r,i,j)
{'fraction_non_alphanumeric': 0.07266751871462479, 'fraction_numerical': 0.0025561438743837866, 'mean_word_length': 4.805511393746688, 'pattern_counts': {'":': 0, '<': 159, '<?xml version=': 0, '>': 159, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1397517', 'n_tokens_mistral': 3459, 'n_tokens_neox': 3324, 'n_words': 1503}