doc: document how to inspect sets and relations

diff --git a/doc/user.pod b/doc/user.pod
index 1818ddd..aba18ea 100644 (file)
--- a/doc/user.pod
+++ b/doc/user.pod
@@ -624,6 +624,78 @@ Or, alternatively,
        bset = isl_basic_set_read_from_str(ctx,
                "{[i] : exists (a : i = 2a and i >= 10 and i <= 42)}", -1);
 
+=head2 Inspecting Sets and Relations
+
+Usually, the user should not have to care about the actual constraints
+of the sets and maps, but should instead apply the abstract operations
+explained in the following sections.
+Occasionally, however, it may be required to inspect the individual
+coefficients of the constraints.  This section explains how to do so.
+In these cases, it may also be useful to have C<isl> compute
+an explicit representation of the existentially quantified variables.
+
+       __isl_give isl_set *isl_set_compute_divs(
+               __isl_take isl_set *set);
+       __isl_give isl_map *isl_map_compute_divs(
+               __isl_take isl_map *map);
+
+This explicit representation defines the existentially quantified
+variables as integer divisions of the other variables, possibly
+including earlier existentially quantified variables.
+An explicitly represented existentially quantified variable therefore
+has a unique value when the values of the other variables are known.
+
+To iterate over all the basic sets or maps in a set or map, use
+
+       int isl_set_foreach_basic_set(__isl_keep isl_set *set,
+               int (*fn)(__isl_take isl_basic_set *bset, void *user),
+               void *user);
+       int isl_map_foreach_basic_map(__isl_keep isl_map *map,
+               int (*fn)(__isl_take isl_basic_map *bmap, void *user),
+               void *user);
+
+The callback function C<fn> should return 0 if successful and
+-1 if an error occurs.  In the latter case, or if any other error
+occurs, the above functions will return -1.
+
+To iterate over the constraints of a basic set or map, use
+
+       #include <isl_constraint.h>
+
+       int isl_basic_map_foreach_constraint(
+               __isl_keep isl_basic_map *bmap,
+               int (*fn)(__isl_take isl_constraint *c, void *user),
+               void *user);
+       void isl_constraint_free(struct isl_constraint *c);
+
+Again, the callback function C<fn> should return 0 if successful and
+-1 if an error occurs.  In the latter case, or if any other error
+occurs, the above functions will return -1.
+
+The coefficients of the constraints can be inspected using
+the following functions.
+
+       void isl_constraint_get_constant(
+               __isl_keep isl_constraint *constraint, isl_int *v);
+       void isl_constraint_get_coefficient(
+               __isl_keep isl_constraint *constraint,
+               enum isl_dim_type type, int pos, isl_int *v);
+
+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
+if the inspected set or map is the result of a call
+to C<isl_set_compute_divs> or C<isl_map_compute_divs>.
+
+       __isl_give isl_div *isl_constraint_div(
+               __isl_keep isl_constraint *constraint, int pos);
+       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);
+
 =head2 Properties
 
 =head3 Unary Properties

diff --git a/include/isl_constraint.h b/include/isl_constraint.h
index a1ec0ed..a79f22e 100644 (file)
--- a/include/isl_constraint.h
+++ b/include/isl_constraint.h
@@ -63,14 +63,16 @@ int isl_basic_set_has_defining_inequalities(
 int isl_constraint_dim(struct isl_constraint *constraint,
        enum isl_dim_type type);
 
-void isl_constraint_get_constant(struct isl_constraint *constraint, isl_int *v);
-void isl_constraint_get_coefficient(struct isl_constraint *constraint,
+void isl_constraint_get_constant(__isl_keep isl_constraint *constraint,
+       isl_int *v);
+void isl_constraint_get_coefficient(__isl_keep isl_constraint *constraint,
        enum isl_dim_type type, int pos, isl_int *v);
 void isl_constraint_set_constant(__isl_keep isl_constraint *constraint, isl_int v);
 void isl_constraint_set_coefficient(__isl_keep isl_constraint *constraint,
        enum isl_dim_type type, int pos, isl_int v);
 
-struct isl_div *isl_constraint_div(struct isl_constraint *constraint, int pos);
+__isl_give isl_div *isl_constraint_div(__isl_keep isl_constraint *constraint,
+       int pos);
 struct isl_constraint *isl_constraint_add_div(struct isl_constraint *constraint,
        struct isl_div *div, int *pos);
 

diff --git a/include/isl_div.h b/include/isl_div.h
index 781f91e..1c97f0e 100644 (file)
--- a/include/isl_div.h
+++ b/include/isl_div.h
@@ -24,15 +24,16 @@ struct isl_div {
        struct isl_basic_map    *bmap;
        isl_int                 **line;
 };
+typedef struct isl_div isl_div;
 
 struct isl_div *isl_div_alloc(struct isl_dim *dim);
 struct isl_div *isl_basic_map_div(struct isl_basic_map *bmap, int pos);
 struct isl_div *isl_basic_set_div(struct isl_basic_set *bset, int pos);
 void isl_div_free(struct isl_div *c);
 
-void isl_div_get_constant(struct isl_div *div, isl_int *v);
-void isl_div_get_denominator(struct isl_div *div, isl_int *v);
-void isl_div_get_coefficient(struct 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);
 void isl_div_set_constant(struct isl_div *div, isl_int v);
 void isl_div_set_denominator(struct isl_div *div, isl_int v);

diff --git a/include/isl_set.h b/include/isl_set.h
index fc354c6..ab020d7 100644 (file)
--- a/include/isl_set.h
+++ b/include/isl_set.h
@@ -257,7 +257,7 @@ int isl_set_is_strict_subset(__isl_keep isl_set *set1, __isl_keep isl_set *set2)
 int isl_set_is_equal(__isl_keep isl_set *set1, __isl_keep isl_set *set2);
 
 struct isl_set *isl_basic_set_compute_divs(struct isl_basic_set *bset);
-struct isl_set *isl_set_compute_divs(struct isl_set *set);
+__isl_give isl_set *isl_set_compute_divs(__isl_take isl_set *set);
 
 struct isl_basic_set *isl_set_copy_basic_set(struct isl_set *set);
 struct isl_set *isl_set_drop_basic_set(struct isl_set *set,