drop "nparam" argument from isl_{set,map}_read_from_{file,str}
[platform/upstream/isl.git] / doc / user.pod
index 5ab6313..ede38e8 100644 (file)
@@ -112,6 +112,43 @@ of explicitly creating a parameter space.  These can now be created
 directly using C<isl_space_params_alloc> or from other spaces using
 C<isl_space_params>.
 
+=item * The space in which C<isl_aff>, C<isl_pw_aff>, C<isl_qpolynomial>,
+C<isl_pw_qpolynomial>, C<isl_qpolynomial_fold> and C<isl_pw_qpolynomial_fold>
+objects live is now a map space
+instead of a set space.  This means, for example, that the dimensions
+of the domain of an C<isl_aff> are now considered to be of type
+C<isl_dim_in> instead of C<isl_dim_set>.  Extra functions have been
+added to obtain the domain space.  Some of the constructors still
+take a domain space and have therefore been renamed.
+
+=item * The functions C<isl_equality_alloc> and C<isl_inequality_alloc>
+now take an C<isl_local_space> instead of an C<isl_space>.
+An C<isl_local_space> can be created from an C<isl_space>
+using C<isl_local_space_from_space>.
+
+=item * The C<isl_div> type has been removed.  Functions that used
+to return an C<isl_div> now return an C<isl_aff>.
+Note that the space of an C<isl_aff> is that of relation.
+When replacing a call to C<isl_div_get_coefficient> by a call to
+C<isl_aff_get_coefficient> any C<isl_dim_set> argument needs
+to be replaced by C<isl_dim_in>.
+A call to C<isl_aff_from_div> can be replaced by a call
+to C<isl_aff_floor>.
+A call to C<isl_qpolynomial_div(div)> call be replaced by
+the nested call
+
+       isl_qpolynomial_from_aff(isl_aff_floor(div))
+
+The function C<isl_constraint_div> has also been renamed
+to C<isl_constraint_get_div>.
+
+=item * The C<nparam> argument has been removed from
+C<isl_map_read_from_str> and similar functions.
+When reading input in the original PolyLib format,
+the result will have no parameters.
+If parameters are expected, the caller may want to perform
+dimension manipulation on the result.
+
 =back
 
 =head1 Installation
@@ -533,20 +570,32 @@ of the original object.
                __isl_keep isl_constraint *constraint);
 
        #include <isl/polynomial.h>
+       __isl_give isl_space *isl_qpolynomial_get_domain_space(
+               __isl_keep isl_qpolynomial *qp);
        __isl_give isl_space *isl_qpolynomial_get_space(
                __isl_keep isl_qpolynomial *qp);
        __isl_give isl_space *isl_qpolynomial_fold_get_space(
                __isl_keep isl_qpolynomial_fold *fold);
+       __isl_give isl_space *isl_pw_qpolynomial_get_domain_space(
+               __isl_keep isl_pw_qpolynomial *pwqp);
        __isl_give isl_space *isl_pw_qpolynomial_get_space(
                __isl_keep isl_pw_qpolynomial *pwqp);
+       __isl_give isl_space *isl_pw_qpolynomial_fold_get_domain_space(
+               __isl_keep isl_pw_qpolynomial_fold *pwf);
+       __isl_give isl_space *isl_pw_qpolynomial_fold_get_space(
+               __isl_keep isl_pw_qpolynomial_fold *pwf);
        __isl_give isl_space *isl_union_pw_qpolynomial_get_space(
                __isl_keep isl_union_pw_qpolynomial *upwqp);
        __isl_give isl_space *isl_union_pw_qpolynomial_fold_get_space(
                __isl_keep isl_union_pw_qpolynomial_fold *upwf);
 
        #include <isl/aff.h>
+       __isl_give isl_space *isl_aff_get_domain_space(
+               __isl_keep isl_aff *aff);
        __isl_give isl_space *isl_aff_get_space(
                __isl_keep isl_aff *aff);
+       __isl_give isl_space *isl_pw_aff_get_domain_space(
+               __isl_keep isl_pw_aff *pwaff);
        __isl_give isl_space *isl_pw_aff_get_space(
                __isl_keep isl_pw_aff *pwaff);
 
@@ -611,7 +660,7 @@ using the following functions.
        const char *isl_space_get_tuple_name(__isl_keep isl_space *space,
                enum isl_dim_type type);
 
-The C<dim> argument needs to be one of C<isl_dim_in>, C<isl_dim_out>
+The C<type> argument needs to be one of C<isl_dim_in>, C<isl_dim_out>
 or C<isl_dim_set>.  As with C<isl_space_get_name>,
 the C<isl_space_get_tuple_name> function returns a pointer to some internal
 data structure.
@@ -691,6 +740,7 @@ They can be inspected, copied and freed using the following functions.
        #include <isl/local_space.h>
        isl_ctx *isl_local_space_get_ctx(
                __isl_keep isl_local_space *ls);
+       int isl_local_space_is_set(__isl_keep isl_local_space *ls);
        int isl_local_space_dim(__isl_keep isl_local_space *ls,
                enum isl_dim_type type);
        const char *isl_local_space_get_dim_name(
@@ -701,7 +751,7 @@ They can be inspected, copied and freed using the following functions.
                enum isl_dim_type type, unsigned pos, const char *s);
        __isl_give isl_space *isl_local_space_get_space(
                __isl_keep isl_local_space *ls);
-       __isl_give isl_div *isl_local_space_get_div(
+       __isl_give isl_aff *isl_local_space_get_div(
                __isl_keep isl_local_space *ls, int pos);
        __isl_give isl_local_space *isl_local_space_copy(
                __isl_keep isl_local_space *ls);
@@ -791,23 +841,23 @@ dimensions is zero.
 
        #include <isl/set.h>
        __isl_give isl_basic_set *isl_basic_set_read_from_file(
-               isl_ctx *ctx, FILE *input, int nparam);
+               isl_ctx *ctx, FILE *input);
        __isl_give isl_basic_set *isl_basic_set_read_from_str(
-               isl_ctx *ctx, const char *str, int nparam);
+               isl_ctx *ctx, const char *str);
        __isl_give isl_set *isl_set_read_from_file(isl_ctx *ctx,
-               FILE *input, int nparam);
+               FILE *input);
        __isl_give isl_set *isl_set_read_from_str(isl_ctx *ctx,
-               const char *str, int nparam);
+               const char *str);
 
        #include <isl/map.h>
        __isl_give isl_basic_map *isl_basic_map_read_from_file(
-               isl_ctx *ctx, FILE *input, int nparam);
+               isl_ctx *ctx, FILE *input);
        __isl_give isl_basic_map *isl_basic_map_read_from_str(
-               isl_ctx *ctx, const char *str, int nparam);
+               isl_ctx *ctx, const char *str);
        __isl_give isl_map *isl_map_read_from_file(
-               isl_ctx *ctx, FILE *input, int nparam);
+               isl_ctx *ctx, FILE *input);
        __isl_give isl_map *isl_map_read_from_str(isl_ctx *ctx,
-               const char *str, int nparam);
+               const char *str);
 
        #include <isl/union_set.h>
        __isl_give isl_union_set *isl_union_set_read_from_file(
@@ -823,13 +873,6 @@ dimensions is zero.
 
 The input format is autodetected and may be either the C<PolyLib> format
 or the C<isl> format.
-C<nparam> specifies how many of the final columns in
-the C<PolyLib> format correspond to parameters.
-If input is given in the C<isl> format, then the number
-of parameters needs to be equal to C<nparam>.
-If C<nparam> is negative, then any number of parameters
-is accepted in the C<isl> format and zero parameters
-are assumed in the C<PolyLib> format.
 
 =head3 Output
 
@@ -1054,9 +1097,9 @@ using the following functions.
 
        #include <isl/constraint.h>
        __isl_give isl_constraint *isl_equality_alloc(
-               __isl_take isl_space *space);
+               __isl_take isl_local_space *ls);
        __isl_give isl_constraint *isl_inequality_alloc(
-               __isl_take isl_space *space);
+               __isl_take isl_local_space *ls);
        __isl_give isl_constraint *isl_constraint_set_constant(
                __isl_take isl_constraint *constraint, isl_int v);
        __isl_give isl_constraint *isl_constraint_set_constant_si(
@@ -1086,45 +1129,37 @@ using the following functions.
 For example, to create a set containing the even integers
 between 10 and 42, you would use the following code.
 
-       isl_int v;
        isl_space *space;
+       isl_local_space *ls;
        isl_constraint *c;
        isl_basic_set *bset;
 
-       isl_int_init(v);
        space = isl_space_set_alloc(ctx, 0, 2);
        bset = isl_basic_set_universe(isl_space_copy(space));
+       ls = isl_local_space_from_space(space);
 
-       c = isl_equality_alloc(isl_space_copy(space));
-       isl_int_set_si(v, -1);
-       isl_constraint_set_coefficient(c, isl_dim_set, 0, v);
-       isl_int_set_si(v, 2);
-       isl_constraint_set_coefficient(c, isl_dim_set, 1, v);
+       c = isl_equality_alloc(isl_local_space_copy(ls));
+       c = isl_constraint_set_coefficient_si(c, isl_dim_set, 0, -1);
+       c = isl_constraint_set_coefficient_si(c, isl_dim_set, 1, 2);
        bset = isl_basic_set_add_constraint(bset, c);
 
-       c = isl_inequality_alloc(isl_space_copy(space));
-       isl_int_set_si(v, -10);
-       isl_constraint_set_constant(c, v);
-       isl_int_set_si(v, 1);
-       isl_constraint_set_coefficient(c, isl_dim_set, 0, v);
+       c = isl_inequality_alloc(isl_local_space_copy(ls));
+       c = isl_constraint_set_constant_si(c, -10);
+       c = isl_constraint_set_coefficient_si(c, isl_dim_set, 0, 1);
        bset = isl_basic_set_add_constraint(bset, c);
 
-       c = isl_inequality_alloc(space);
-       isl_int_set_si(v, 42);
-       isl_constraint_set_constant(c, v);
-       isl_int_set_si(v, -1);
-       isl_constraint_set_coefficient(c, isl_dim_set, 0, v);
+       c = isl_inequality_alloc(ls);
+       c = isl_constraint_set_constant_si(c, 42);
+       c = isl_constraint_set_coefficient_si(c, isl_dim_set, 0, -1);
        bset = isl_basic_set_add_constraint(bset, c);
 
        bset = isl_basic_set_project_out(bset, isl_dim_set, 1, 1);
 
-       isl_int_clear(v);
-
 Or, alternatively,
 
        isl_basic_set *bset;
        bset = isl_basic_set_read_from_str(ctx,
-               "{[i] : exists (a : i = 2a and i >= 10 and i <= 42)}", -1);
+               "{[i] : exists (a : i = 2a and i >= 10 and i <= 42)}");
 
 A basic set or relation can also be constructed from two matrices
 describing the equalities and the inequalities.
@@ -1298,20 +1333,17 @@ the following functions.
                enum isl_dim_type type, unsigned first, unsigned n);
 
 The explicit representations of the existentially quantified
-variables can be inspected using the following functions.
-Note that the user is only allowed to use these functions
+variables can be inspected using the following function.
+Note that the user is only allowed to use this function
 if the inspected set or map is the result of a call
 to C<isl_set_compute_divs> or C<isl_map_compute_divs>.
+The existentially quantified variable is equal to the floor
+of the returned affine expression.  The affine expression
+itself can be inspected using the functions in
+L<"Piecewise Quasi Affine Expressions">.
 
-       __isl_give isl_div *isl_constraint_div(
+       __isl_give isl_aff *isl_constraint_get_div(
                __isl_keep isl_constraint *constraint, int pos);
-       isl_ctx *isl_div_get_ctx(__isl_keep isl_div *div);
-       void isl_div_get_constant(__isl_keep isl_div *div,
-               isl_int *v);
-       void isl_div_get_denominator(__isl_keep isl_div *div,
-               isl_int *v);
-       void isl_div_get_coefficient(__isl_keep isl_div *div,
-               enum isl_dim_type type, int pos, isl_int *v);
 
 To obtain the constraints of a basic set or map in matrix
 form, use the following functions.
@@ -2049,6 +2081,26 @@ All parameters need to be named.
        __isl_give isl_map *isl_map_insert_dims(
                __isl_take isl_map *map,
                enum isl_dim_type type, unsigned pos, unsigned n);
+       __isl_give isl_basic_set *isl_basic_set_move_dims(
+               __isl_take isl_basic_set *bset,
+               enum isl_dim_type dst_type, unsigned dst_pos,
+               enum isl_dim_type src_type, unsigned src_pos,
+               unsigned n);
+       __isl_give isl_basic_map *isl_basic_map_move_dims(
+               __isl_take isl_basic_map *bmap,
+               enum isl_dim_type dst_type, unsigned dst_pos,
+               enum isl_dim_type src_type, unsigned src_pos,
+               unsigned n);
+       __isl_give isl_set *isl_set_move_dims(
+               __isl_take isl_set *set,
+               enum isl_dim_type dst_type, unsigned dst_pos,
+               enum isl_dim_type src_type, unsigned src_pos,
+               unsigned n);
+       __isl_give isl_map *isl_map_move_dims(
+               __isl_take isl_map *map,
+               enum isl_dim_type dst_type, unsigned dst_pos,
+               enum isl_dim_type src_type, unsigned src_pos,
+               unsigned n);
 
 It is usually not advisable to directly change the (input or output)
 space of a set or a relation as this removes the name and the internal
@@ -2248,6 +2300,9 @@ instead.
                __isl_take isl_basic_set *context);
        __isl_give isl_set *isl_set_gist(__isl_take isl_set *set,
                __isl_take isl_set *context);
+       __isl_give isl_set *isl_set_gist_params(
+               __isl_take isl_set *set,
+               __isl_take isl_set *context);
        __isl_give isl_union_set *isl_union_set_gist(
                __isl_take isl_union_set *uset,
                __isl_take isl_union_set *context);
@@ -2256,6 +2311,9 @@ instead.
                __isl_take isl_basic_map *context);
        __isl_give isl_map *isl_map_gist(__isl_take isl_map *map,
                __isl_take isl_map *context);
+       __isl_give isl_map *isl_map_gist_params(
+               __isl_take isl_map *map,
+               __isl_take isl_set *context);
        __isl_give isl_union_map *isl_union_map_gist(
                __isl_take isl_union_map *umap,
                __isl_take isl_union_map *context);
@@ -2448,15 +2506,13 @@ the original and the kernel (in that order) is the zero matrix.
 
 =head2 Piecewise Quasi Affine Expressions
 
-The zero quasi affine expression can be created using
+The zero quasi affine expression on a given domain can be created using
 
-       __isl_give isl_aff *isl_aff_zero(
+       __isl_give isl_aff *isl_aff_zero_on_domain(
                __isl_take isl_local_space *ls);
 
-A quasi affine expression can also be initialized from an C<isl_div>:
-
-       #include <isl/div.h>
-       __isl_give isl_aff *isl_aff_from_div(__isl_take isl_div *div);
+Note that the space in which the resulting object lives is a map space
+with the given space as domain and a one-dimensional range.
 
 An empty piecewise quasi affine expression (one with no cells)
 or a piecewise quasi affine expression with a single cell can
@@ -2511,6 +2567,8 @@ The expression can be inspected using
        isl_ctx *isl_aff_get_ctx(__isl_keep isl_aff *aff);
        int isl_aff_dim(__isl_keep isl_aff *aff,
                enum isl_dim_type type);
+       __isl_give isl_local_space *isl_aff_get_domain_local_space(
+               __isl_keep isl_aff *aff);
        __isl_give isl_local_space *isl_aff_get_local_space(
                __isl_keep isl_aff *aff);
        const char *isl_aff_get_dim_name(__isl_keep isl_aff *aff,
@@ -2521,7 +2579,7 @@ The expression can be inspected using
                enum isl_dim_type type, int pos, isl_int *v);
        int isl_aff_get_denominator(__isl_keep isl_aff *aff,
                isl_int *v);
-       __isl_give isl_div *isl_aff_get_div(
+       __isl_give isl_aff *isl_aff_get_div(
                __isl_keep isl_aff *aff, int pos);
 
        int isl_pw_aff_foreach_piece(__isl_keep isl_pw_aff *pwaff,
@@ -2931,27 +2989,29 @@ More complicated quasipolynomials can be created by applying
 operations such as addition and multiplication
 on the resulting quasipolynomials
 
-       __isl_give isl_qpolynomial *isl_qpolynomial_zero(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_one(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_infty(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_neginfty(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_nan(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_rat_cst(
-               __isl_take isl_space *dim,
+       __isl_give isl_qpolynomial *isl_qpolynomial_zero_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_one_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_infty_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_neginfty_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_nan_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_rat_cst_on_domain(
+               __isl_take isl_space *domain,
                const isl_int n, const isl_int d);
-       __isl_give isl_qpolynomial *isl_qpolynomial_div(
-               __isl_take isl_div *div);
-       __isl_give isl_qpolynomial *isl_qpolynomial_var(
-               __isl_take isl_space *dim,
+       __isl_give isl_qpolynomial *isl_qpolynomial_var_on_domain(
+               __isl_take isl_space *domain,
                enum isl_dim_type type, unsigned pos);
        __isl_give isl_qpolynomial *isl_qpolynomial_from_aff(
                __isl_take isl_aff *aff);
 
+Note that the space in which a quasipolynomial lives is a map space
+with a one-dimensional range.  The C<domain> argument in some of
+the functions above corresponds to the domain of this map space.
+
 The zero piecewise quasipolynomial or a piecewise quasipolynomial
 with a single cell can be created using the following functions.
 Multiple of these single cell piecewise quasipolynomials can
@@ -3055,7 +3115,7 @@ these functions
                isl_int *d);
        int isl_term_get_exp(__isl_keep isl_term *term,
                enum isl_dim_type type, unsigned pos);
-       __isl_give isl_div *isl_term_get_div(
+       __isl_give isl_aff *isl_term_get_div(
                __isl_keep isl_term *term, unsigned pos);
        void isl_term_free(__isl_take isl_term *term);