FilterHomomorphism (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.design.kernel

## Class FilterHomomorphism

- java.lang.Object
- - hlt.language.design.kernel.Expression
  - - hlt.language.design.kernel.ProtoExpression
    - - hlt.language.design.kernel.Homomorphism
      - - hlt.language.design.kernel.FilterHomomorphism

- All Implemented Interfaces:
    Locatable

      public class FilterHomomorphism
      extends Homomorphism

  This is a refinement of the `Homomorphism` class using a filter in the form of a boolean function sifting those elements of the collection on which to apply the function. More precisely, it is the built-in version of the general computation scheme whose instance is the following "fhom" functional, which may be formulated recursively, for the case of a list collection, as:

            fhom[list,op,id](filter,f) = if   isEmpty(list)
                                         then id
                                         else let elt = head(list)
                                              in  if   filter(elt)
                                                  then op(f(elt),fhom[tail(list),op,id](filter,f))
                                                  else fhom[tail(list),op,id](filter,f)

  This class is defined to enable an optimization of monoid comprehensions where a boolean qualifier can be integrated directly into the homomorphism preceding it, thus doing away with the generation of a larger set than necessary. When this is used after normalizing monoid comprehension with unnesting of conditions to the uppermost scope they control together with gathering them into a single logical `and`, the net effect is a drastic reduction of the size of loops. Recall that a monoid comprehension is an expression of the form:

       [op,id] { e | q1, ..., qn }

  where `[op,id]` define a monoid, `e` is an expression, and the `qi`'s are qualifiers. A qualifier is either a (boolean) expression or a pair `x <- e`, where `x` is a variable and `e` is a (collection) expression. After normalization, there may be at most one boolean qualifier in the sequence (which may also be empty). Such a normalized monoid comprehension can then be translated as follows:

       [op,id]{e | } = op(e,id);

       [op,id]{e | c} = if c then op(e,id) else id;

       [op,id]{e | x <- e', c, Q} = f_hom(e', lambda x.[op,id]{e | Q}, op, id, lambda x.c);

       [op,id]{e | x <- e', y <- e'', Q} = hom(e', lambda x.[op,id]{e | y <- e'', Q}, op, id);

- - ### Field Summary

    - ### Fields inherited from class hlt.language.design.kernel.Homomorphism

      `DEFAULT_IN_PLACE, DISABLED_IN_PLACE, ENABLED_IN_PLACE`

    - ### Fields inherited from class hlt.language.design.kernel.Expression

      `VOID_ASSIGNMENTS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FilterHomomorphism(Tables tables, Expression collection, Expression function, Expression operation, Expression identity, Expression filter)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `compile(Compiler compiler)` This method compiles this expression in the context of the specified `Compiler`.
    `Expression` | `copy()` Returns a deep copy of this expression.
    `int` | `numberOfSubexpressions()` Returns the number of subexpressions
    `void` | `setCheckedType()` This method sets the final unambiguously checked type of this expression, possibly along with other final information that may be needed by the compiler for generating code.
    `Expression` | `setSubexpression(int n, Expression expression)` Returns this expression after setting its n-th subexpression to the specified expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
    `Expression` | `subexpression(int n)` Returns the n-th subexpression of this expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
    `java.lang.String` | `toString()`
    `void` | `typeCheck(TypeChecker typeChecker)` Checking the type of a homomorphism depends on whether the homomorphism is...
    `Expression` | `typedCopy()` Returns a deep copy of this expression this and all its subexpressions share the same type as their copy's counterparts.

    - ### Methods inherited from class hlt.language.design.kernel.Homomorphism

      `disableInPlace, enableInPlace, setSlicings, setSlicings`

    - ### Methods inherited from class hlt.language.design.kernel.ProtoExpression

      `checkedType, setCheckedType, setType, type, typeRef`

    - ### Methods inherited from class hlt.language.design.kernel.Expression

      `addType, addTypes, boxSort, containsFreeName, enclosingScope, extent, getEnd, getStart, isConstant, isEquality, isFalse, isHiddenSlicing, isNull, isSelector, isSlicing, isTrue, isVoid, locationString, otherTypes, parameters, sanitizeNames, sanitizeSorts, setCheckedTypeLocked, setEnd, setExtent, setOtherTypes, setStart, shiftOffsets, shiftOffsets, sort, substitute, typeCheck, typeCheck, typeCheckLocked`

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### FilterHomomorphism

          public FilterHomomorphism(Tables tables,
                            Expression collection,
                            Expression function,
                            Expression operation,
                            Expression identity,
                            Expression filter)

  - ### Method Detail

    - #### copy

          public final Expression copy()

      Description copied from class: `Expression`
      Returns a deep copy of this expression. The types are not not copied. NB: This is a convenience for building expressions that should be used exclusively before any processing (in particular sanitizing), is done on this expression.
      Overrides:
        `copy` in class `Homomorphism`

    - #### typedCopy

          public final Expression typedCopy()

      Description copied from class: `Expression`
      Returns a deep copy of this expression this and all its subexpressions share the same type as their copy's counterparts. NB: This is a convenience for building expressions that should be used exclusively before any processing (in particular sanitizing), is done on this expression.
      Overrides:
        `typedCopy` in class `Homomorphism`

    - #### numberOfSubexpressions

          public int numberOfSubexpressions()

      Returns the number of subexpressions
      Overrides:
        `numberOfSubexpressions` in class `Homomorphism`

    - #### subexpression

          public final Expression subexpression(int n)
                                         throws NoSuchSubexpressionException

      Returns the n-th subexpression of this expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
      Overrides:
        `subexpression` in class `Homomorphism`
      Throws:
        `NoSuchSubexpressionException`

    - #### setSubexpression

          public final Expression setSubexpression(int n,
                                    Expression expression)
                                            throws NoSuchSubexpressionException

      Description copied from class: `Expression`
      Returns this expression after setting its n-th subexpression to the specified expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
      Overrides:
        `setSubexpression` in class `Homomorphism`
      Throws:
        `NoSuchSubexpressionException`

    - #### typeCheck

          public final void typeCheck(TypeChecker typeChecker)
                               throws TypingErrorException

      Description copied from class: `Homomorphism`
      Checking the type of a homomorphism depends on whether the homomorphism is...

              Primitive:                     OR     Collection:

           _collection : from_collection(A)       _collection : from_collection(A)
             _function : A -> B                     _function : A -> to_collection(B)
            _operation : B,B -> B                  _operation : B, to_collection(B) -> to_collection(B)
            _identity  : B                          _identity : to_collection(B)
                  this : B                               this : to_collection(B)

      Also, if slicing expressions are present, they must be typed as booleans.

      NB: In order to accommodate primitive homomorphisms whose monoid operation is not strictly-speaking internal but may involve subtyping, we use a work-around that consists of unifying the shadow types of the operation's arguments rather than the types themselves. The changes from the lines needed for typing such "loose" monoids are marked explicitly and the original lines they replace are commented out. Unifying shadow types is done using a special goal: a `ShadowUnifyGoal`.

      Overrides:
        `typeCheck` in class `Homomorphism`
      Throws:
        `TypingErrorException`

    - #### setCheckedType

          public final void setCheckedType()

      Description copied from class: `Expression`
      This method sets the final unambiguously checked type of this expression, possibly along with other final information that may be needed by the compiler for generating code.
      Overrides:
        `setCheckedType` in class `Homomorphism`

    - #### compile

          public final void compile(Compiler compiler)

      Description copied from class: `Expression`
      This method compiles this expression in the context of the specified `Compiler`.
      Overrides:
        `compile` in class `Homomorphism`

    - #### toString

          public final java.lang.String toString()

      Overrides:
        `toString` in class `Homomorphism`