Environments (ap_environment.h)

Environments bind variables (of level 1) to dimensions (of level 0).

datatype: ap_environment_t

Internal datatype for environments.

For information, the definition is:

typedef struct ap_environment_t {
  ap_var_t* var_of_dim;
  /*
    Array of size intdim+realdim, indexed by dimensions.
    - It should not contain identical strings..
    - Slice [0..intdim-1] is lexicographically sorted,
      and denotes integer variables.
    - Slice [intdim..intdim+realdim-1] is lexicographically sorted,
      and denotes real variables.
    - The memory allocated for the variables are attached to the structure
      (they are freed when the structure is no longer in use)
  */
  size_t intdim; /* Number of integer variables */
  size_t realdim;/* Number of real variables */
  size_t count; /* For reference counting */
} ap_environment_t;

Function: void ap_environment_free (ap_environment_t* env)

Function: ap_environment_t* ap_environment_copy (ap_environment_t* env)

Respectively free and duplicate an environment.

(copy is cheap, as environments are managed with reference counters).

Function: void ap_environment_fdump (FILE* stream, ap_environment_t* env)

Print an environment under the form:

  environment: dim = (..,..), count = ..
  0: name0
  1: name1
  ...

Function: ap_environment_t* ap_environment_alloc_empty ()

Build an empty environment.

Function: ap_environment_t* ap_environment_alloc (ap_var_t* var_of_intdim, size_t intdim, ap_var_t* var_of_realdim, size_t realdim)

Build an environment from an array of integer and an array of real variables.

var_of_intdim is an array of variables of size intdim, var_of_realdim is an array of variables of size realdim. Pointers to arrays may be NULL if their size is 0.

Variables are duplicated in the result, so it is the responsability of the user to free the variables he provides.

If some variables are duplicated, return NULL.

Function: ap_environment_t* ap_environment_add (ap_environment_t* env, ap_var_t* var_of_intdim, size_t intdim, ap_var_t* var_of_realdim, size_t realdim)

Function: ap_environment_t* ap_environment_remove (ap_environment_t* env, ap_var_t* tvar, size_t size)

Resp. add or remove new variables to an existing environment, with a functional semantics. Same conventions as for ap_environment_alloc function apply. If the result is non-sense (or in case of attempt to remove an unknwon variable), return NULL.

Function: ap_dim_t ap_environment_dim_of_var (ap_environment_t* env, ap_var_t var)

Convert a variable in its corresponding dimension in the environment env. If var is unknown in env, return AP_DIM_MAX.

Function: ap_dim_t ap_environment_var_of_dim (ap_environment_t* env, ap_dim_t dim)

Return the variable associated to the dimension dim in the environment env. There is no bound check here.

The remaining functions are much less useful for normal user.

Function: bool ap_environment_is_eq (ap_environment_t* env1, ap_environment_t* env2)

Function: bool ap_environment_is_leq (ap_environment_t* env1, ap_environment_t* env2)

Resp. test the equality and the inclusion of two environments.

Function: int ap_environment_compare (ap_environment_t* env1, ap_environment_t* env2)

Return:

-2

if the environments are not compatible (a variable has a different type in the 2 environments);

-1

if env1 is a subset of (included in) env2;

0

if they are equal;

+1

if env1 is a superset of env2;

+2

otherwise: the least common environment exists and is a strict superset of both environments.

Function: int ap_environment_hash (ap_environment_t* env)

Return an hash code for an environment.

Function: ap_dimchange_t* ap_environment_dimchange (ap_environment_t* env1, ap_environment_t* env)

Compute the transformation for converting from an environment env1 to a superenvironment env. Return NULL if env is not a superenvironment.

Function: ap_dimchange2_t* ap_environment_dimchange2 (ap_environment_t* env1, ap_environment_t* env2)

Compute the transformation for switching from an environment env1 to an env2, by first adding (some) variables of env2, and then removing (some) variables of env1. Return NULL if env1 and env2 ar enot compatible environments.

Function: ap_environment_t* ap_environment_lce (ap_environment_t* env1, ap_environment_t* env2, ap_dimchange_t** dimchange1, ap_dimchange_t** dimchange2)

Least common environment to two enviroenments.

• Assume ap_environment_is_eq(env1,env2)==false
• If environments are not compatible (a variable has different types in the 2 environments), return NULL
• Compute also in dimchange1 and dimchange2 the conversion transformations to the lce.
• If no dimensions to add to env1, this implies that env is actually env1. In this case, *dimchange1==NULL. Otherwise, the function allocates the *dimchange1 with ap_dimchange_alloc.

Function: ap_environment_t* ap_environment_lce_array (ap_environment_t** tenv, size_t size, ap_dimchange_t*** ptdimchange)

Least common environment to an array of environments.

• Assume the size size of the array tenv is at least one;
• If all input environments are the same, *ptdimchange==NULL. Otherwise, compute in *ptdimchange the conversion permutations
• If no dimensions to add to tenv[i], this implies that the result is actually tenv[i]. In this case, (*ptdimchange)[i]==NULL. Otherwise, the function allocates the (*ptdimchange)[i] with ap_dimchange_alloc.

Function: ap_environment_t* ap_environment_rename (ap_environment_t* env, ap_var_t* tvar1, ap_var_t* tvar2, size_t size, ap_dimperm_t* perm)

Rename the variables in the environment. size is the common size of arrays tvar1 and tvar2, and perm is a result-parameter pointing to an existing but not initialized object of type ap_dimperm_t.

The function applies the variable substitution tvar1[i]->tvar2[i] to the environment, and returns the resulting environment and the allocated transformation permutation in *perm.

If the parameters are not valid, return NULL with perm->dim==NULL.