Package org.apache.sis.math

## Enum FunctionProperty

- Object
- - Enum<FunctionProperty>
  - - FunctionProperty

- All Implemented Interfaces:
    `Serializable`, `Comparable<FunctionProperty>`

      public enum FunctionProperty
      extends Enum<FunctionProperty>

  The manners in which the inputs of a function are mapped to the outputs. The function doesn't need to be mathematical. For example this enumeration can be used with `ObjectConverter`.

  Any given function can have zero, one or more properties from this enumeration. Some properties not included in this enumeration can be expressed by a combination of other properties:

  Inferred function properties
  Property | How to build
  --- | ---
  Bijective | `EnumSet.of(INJECTIVE, SURJECTIVE)`
  Monotonic | `EnumSet.of(INJECTIVE)` or `EnumSet​.of(SURJECTIVE)`
  Strictly increasing | `EnumSet.of(ORDER_PRESERVING, INJECTIVE)`
  Strictly decreasing | `EnumSet.of(ORDER_REVERSING, INJECTIVE)`

  The Javadoc in this class uses the following terms:
  - S (as in source) is the set of all possible input values (the domain).
  - T (as in target) is a set containing all possible output values, and potentially more elements (the codomain). For example the set of output values of the `Integer​.toString()` function is included in a larger set, which is the set of all possible `String` values. In this Javadoc, T stands for the later set.
  Since:
    0.3
  See Also:
    `ObjectConverter​.properties()`

  Defined in the `sis-utility` module

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant | Description
    --- | ---
    `INJECTIVE` | A function is injective if each value of T is either unrelated to S, or is the output of exactly one value of S.
    `INVERTIBLE` | A function is invertible if it can provide an other function mapping T values to S values.
    `ORDER_PRESERVING` | A function preserves order if any sequence of increasing S values is mapped to a sequence of increasing T values.
    `ORDER_REVERSING` | A function reverses order if any sequence of increasing S values is mapped to a sequence of decreasing T values.
    `SURJECTIVE` | A function is surjective if any value of T can be created from one or many values of S.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `isBijective​(Set<FunctionProperty> properties)` | Returns `true` if a function having the given set of properties is bijective.
    `static boolean` | `isMonotonic​(Set<FunctionProperty> properties)` | Returns `true` if a function having the given set of properties is monotonic.
    `static FunctionProperty` | `valueOf​(String name)` | Returns the enum constant of this type with the specified name.
    `static FunctionProperty[]` | `values()` | Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class Enum

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

    - ### Methods inherited from class Object

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

- - ### Enum Constant Detail

    - #### INVERTIBLE

          public static final FunctionProperty INVERTIBLE

      A function is invertible if it can provide an other function mapping T values to S values.

      While other values defined in this enumeration are more about the mathematical aspects of functions, this particular value is more about the programmatical aspect. A function may be conceptually invertible (all bijective functions should be), but the inverse operation may not be implemented. In such case, the function properties shall not include this `INVERTIBLE` value.

      See Also:
        `ObjectConverter​.inverse()`

    - #### INJECTIVE

          public static final FunctionProperty INJECTIVE

      A function is injective if each value of T is either unrelated to S, or is the output of exactly one value of S.
      Example: An `ObjectConverter` doing conversions from `Integer` to `String` is an injective function, because no pair of integers can produce the same string.
      A function which is both injective and surjective is a bijective function. In such functions, there is a one-to-one relationship between all input and output values.
      See Also:
        `SURJECTIVE`, `isBijective(Set)`

    - #### SURJECTIVE

          public static final FunctionProperty SURJECTIVE

      A function is surjective if any value of T can be created from one or many values of S.
      Example: An `ObjectConverter` doing conversions from `String` to `Integer` is a surjective function, since there is always at least one string for each integer value. Note that such function can not be injective since many different strings can represent the same integer value.
      A function which is both injective and surjective is a bijective function. In such functions, there is a one-to-one relationship between all input and output values.
      See Also:
        `INJECTIVE`, `isBijective(Set)`

    - #### ORDER_PRESERVING

          public static final FunctionProperty ORDER_PRESERVING

      A function preserves order if any sequence of increasing S values is mapped to a sequence of increasing T values. This enumeration constant can be used only with `Comparable` types or primitive types having a comparable wrapper.

      Strictly ordered input values are not necessarily mapped to strictly ordered output values. Strictness is preserved only if the function is also injective.

      A function may be both order preserving and order reversing if all input values are mapped to a constant output value.

      See Also:
        `ORDER_REVERSING`, `isMonotonic(Set)`

    - #### ORDER_REVERSING

          public static final FunctionProperty ORDER_REVERSING

      A function reverses order if any sequence of increasing S values is mapped to a sequence of decreasing T values. This enumeration constant can be used only with `Comparable` types or primitive types having a comparable wrapper.

      Strictly ordered input values are not necessarily mapped to strictly ordered output values. Strictness is preserved only if the function is also injective.

      A function may be both order preserving and order reversing if all input values are mapped to a constant output value.

      See Also:
        `ORDER_PRESERVING`, `isMonotonic(Set)`

  - ### Method Detail

    - #### values

          public static FunctionProperty[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (FunctionProperty c : FunctionProperty.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static FunctionProperty valueOf​(String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type has no constant with the specified name
        `NullPointerException` - if the argument is null

    - #### isBijective

          public static boolean isBijective​(Set<FunctionProperty> properties)

      Returns `true` if a function having the given set of properties is bijective. Bijective functions have a one-to-one relationship between all input and output values. This convenience method tests if the given set contains all following properties:
      - `INJECTIVE`
      - `SURJECTIVE`
      Parameters:
        `properties` - the properties of the function to test for bijectivity.
      Returns:
        `true` if a function having the given set of properties is bijective.

    - #### isMonotonic

          public static boolean isMonotonic​(Set<FunctionProperty> properties)

      Returns `true` if a function having the given set of properties is monotonic. This convenience method tests if the given set contains at least one of the following properties:
      - `ORDER_PRESERVING`
      - `ORDER_REVERSING`
      Parameters:
        `properties` - the properties of the function to test for monotonicity.
      Returns:
        `true` if a function having the given set of properties is monotonic.