Package org.apache.groovy.contracts.ast

# Class LoopVariantASTTransformation

java.lang.Object
org.apache.groovy.contracts.ast.LoopVariantASTTransformation

All Implemented Interfaces:
  `CompilationUnitAware`, `ASTTransformation`

public class LoopVariantASTTransformation extends Object implements ASTTransformation, CompilationUnitAware
Handles `Decreases` annotations placed on loop statements (`for`, `while`, `do-while`). The closure must return a value that is non-negative at the start of each iteration and strictly decreases between consecutive iterations.

The transformation injects code to:

1. Evaluate the expression at the start of each iteration.
2. On the first iteration, assert a scalar measure is non-negative at loop entry (well-foundedness).
3. On subsequent iterations, assert it has strictly decreased since the previous iteration start, and is non-negative (GROOVY-12128: comparing iteration starts — rather than the start and end of one pass — sees progress made by a classic `for` loop's update expression, which runs after the body, and does not demand non-negativity after the final body execution).

The final iteration's decrease is intentionally unchecked: a loop that has exited needs no further termination evidence.

Example:

     int n = 10
     @Decreases({ n })
     while (n > 0) {
         n--
     }

Since:
  6.0.0
See Also:
  - `Decreases`
  - `VariantSupport`
  - `LoopVariantViolation`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LoopVariantASTTransformation()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `setCompilationUnit(CompilationUnit unit)`
  Sets the compilation unit currently applying this transformation.
  `void`
  `visit(ASTNode[] nodes, SourceUnit source)`
  Rewrites a loop-level `Decreases` annotation into variant bookkeeping and runtime checks.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### LoopVariantASTTransformation

    public LoopVariantASTTransformation()

- ## Method Details

  - ### setCompilationUnit

    public void setCompilationUnit(CompilationUnit unit)
    Description copied from interface: `CompilationUnitAware`
    Sets the compilation unit currently applying this transformation.
    Specified by:
      `setCompilationUnit` in interface `CompilationUnitAware`
    Parameters:
      `unit` - the active compilation unit

  - ### visit

    public void visit(ASTNode[] nodes, SourceUnit source)
    Rewrites a loop-level `Decreases` annotation into variant bookkeeping and runtime checks.
    Specified by:
      `visit` in interface `ASTTransformation`
    Parameters:
      `nodes` - the annotated AST nodes supplied by the compiler
      `source` - the current source unit