Module org.apache.sis.referencing
Package org.apache.sis.referencing.operation.transform

# Enum Class IterationStrategy

Object
Enum<IterationStrategy>
IterationStrategy

All Implemented Interfaces:
  `Serializable`, `Comparable<IterationStrategy>`, `Constable`

public enum IterationStrategy extends Enum<IterationStrategy>
Strategy for iterating over the point arrays given to `AbstractMathTransform​.transform(…)` methods. If the source and destination arrays are the same and the region of the array to be written overlaps the region of the array to be read, it may be necessary to iterate over the points in reverse order or to copy some points in a temporary array. The `suggest(…)` method in this class returns a strategy suitable to the `transform` arguments.

## Usage

The following code gives a skeleton for a `AbstractMathTransform` implementation capable to transform an array of `double` coordinates:

        public class MyTransform extends AbstractMathTransform {
            @Override
            public void transform(double[] srcPts, int srcOff,
                                  double[] dstPts, int dstOff, int numPts)
            {
                int srcInc = getSourceDimension();
                int dstInc = getTargetDimension();
                if (srcPts == dstPts) {
                    switch (IterationStrategy.suggest(srcOff, srcInc, dstOff, dstInc, numPts)) {
                        case ASCENDING: {
                            break;
                        }
                        case DESCENDING: {
                            srcOff += (numPts-1) * srcInc; srcInc = -srcInc;
                            dstOff += (numPts-1) * dstInc; dstInc = -dstInc;
                            break;
                        }
                        default: {
                            srcPts = Arrays.copyOfRange(srcPts, srcOff, srcOff + numPts*srcInc);
                            srcOff = 0;
                            break;
                        }
                    }
                }
                while (--numPts >= 0) {
                    double x = srcPts[srcOff    ];
                    double y = srcPts[srcOff + 1];
                    double z = srcPts[srcOff + 2];
                    // Repeat as many time as needed for dimension of input points.

                    // Transform (x,y,z) here.

                    dstPts[dstOff    ] = x;
                    dstPts[dstOff + 1] = y;
                    dstPts[dstOff + 2] = z;
                    // Repeat as many time as needed for dimension of output points.

                    srcOff += srcInc;
                    dstOff += dstInc;
                }
            }
        }

Since:
  0.5

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Enum

  `Enum​.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `ASCENDING`
  Iterate over the points in ascending index order.
  `BUFFER_SOURCE`
  Copy the points to transform in a temporary array before to apply the transform.
  `BUFFER_TARGET`
  Write the transformed points in a temporary array and copies them to the destination subarray when the transformation is finished.
  `DESCENDING`
  Iterate over the points in descending index order.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static IterationStrategy`
  `suggest(int srcOff, int srcDim, int dstOff, int dstDim, int numPts)`
  Suggests a strategy for iterating over the points to transform in an array.
  `static IterationStrategy`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static IterationStrategy[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### ASCENDING

    public static final IterationStrategy ASCENDING
    Iterate over the points in ascending index order. There is no need to copy the array.

  - ### DESCENDING

    public static final IterationStrategy DESCENDING
    Iterate over the points in descending index order. There is no need to copy the array.

  - ### BUFFER_SOURCE

    public static final IterationStrategy BUFFER_SOURCE
    Copy the points to transform in a temporary array before to apply the transform. The temporary array will be used for fetching the source coordinates.

    This algorithm can be used as a fallback for any unknown enumeration.

  - ### BUFFER_TARGET

    public static final IterationStrategy BUFFER_TARGET
    Write the transformed points in a temporary array and copies them to the destination subarray when the transformation is finished.

    Developers are allowed to ignore this value and fallback on the same algorithm than `BUFFER_SOURCE`, which is often easier to implement.

- ## Method Details

  - ### values

    public static IterationStrategy[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static IterationStrategy valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### suggest

    public static IterationStrategy suggest(int srcOff, int srcDim, int dstOff, int dstDim, int numPts)
    Suggests a strategy for iterating over the points to transform in an array. This convenience method is provided for `transform` method implementations. It makes the following assumptions:
    - Source and target array are the same.
    - For each coordinate to be transformed, all coordinate values are read before the transformation process starts. For example if a transform goes from geographic to projected CRS, the (longitude, latitude, height) tuple must be completely read before to start writing the (x,y,z) tuple.
    Parameters:
      `srcOff` - the offset in the source coordinate array.
      `srcDim` - the dimension of input points.
      `dstOff` - the offset in the destination coordinate array.
      `dstDim` - the dimension of output points.
      `numPts` - the number of points to transform.
    Returns:
      a strategy for iterating over the points during the transformation process.
    Throws:
      `ArithmeticException` - if the given offsets or number of points are too high.