To: J3                                                     J3/18-165
From: Daniel Celis Garza and Damian Rouson
Subject: An additional macro for ISO_Fortran_binding.h
Date: 2018-May-31
References: N2146, http://bit.ly/ISO_Fortran_binding_h

Introduction
------------
This paper proposes a CFI_INVALID_STRIDE macro that the first author found
useful when writing ISO_Fortran_binding.h and the corresponding C function
definitions.  The resulting ISO_Fortran_binding.h file is available online
(see References above).  N2146 does not define a CFI_INVALID_STRIDE macro.

Use Case
--------
CFI_INVALID_STRIDE is useful when CFI_section is asked to define an array
section where the index ordering is inverted.  In other words, where the
original array's upper bounds become the section's lower bounds and
vice-versa, therefore the stride must be negative. For example, assuming
extents, rank, lower_bounds and upper_bounds are consistent with a valid
array with default bounds.  If strides are not negative, CFI_section could
return CFI_INVALID_STRIDE.  Furthermore, if one of the dimensions is to
have inverted bounds, the corresponding element of strides must be u
negative, else CFI_section will return CFI_INVALID_STRIDE.

Example
-------

int rank=1, ind, extents[1], lower_bounds[1], upper_bounds[1], strides[1];
CFI_CDESC_T (rank) section, source;

ind = CFI_establish(
   (CFI_cdesc_t *) &source, NULL, CFI_attribute_allocatable, CFI_type_int,
   0, rank, extents
);
ind = CFI_establish(
   (CFI_cdesc_t *) &section, NULL, CFI_attribute_other,  CFI_type_int, 0,
   rank, NULL
);
ind = CFI_allocate(
   (CFI_cdesc_t *) &source, lower_bounds, upper_bounds, 0
);
ind = CFI_section(
   (CFI_cdesc_t *) &section, (CFI_cdesc_t *) &source,  upper_bounds,
   lower_bounds, strides
);