Package org.protelis.lang.datatype

Class Option<E>

  • Type Parameters:
    E - the type of instance that can be contained. Option is naturally covariant on this type, so it is safe to cast an Option<T> to Option<S> for any supertype S of T.
    All Implemented Interfaces:
    java.io.Serializable
    public final class Option<E>
extends java.lang.Object
implements java.io.Serializable
    An immutable object that may contain a non-null reference to another object. Each instance of this type either contains a non-null reference, or contains nothing (in which case we say that the reference is "absent"); it is never said to "contain null".

    A non-null Option<E> reference can be used as a replacement for a nullable T reference. It allows you to represent "a T that must be present" and a "a T that might be absent" as two distinct types in your program, which can aid clarity. Protelis recommends to import and use Option when interacting with Java methods that may return null.

    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.Object JAVA_NULL
      Returns the Java null value.

    • Field Detail

      • JAVA_NULL

        public static final java.lang.Object JAVA_NULL
        Returns the Java null value. To be used ONLY for interacting with Java. Protelis is null-intolerant.

    • Method Detail

      • asSet

        public java.util.Set<E> asSet()
        Returns:
        a set representation of the Option, for compatibility with Optional

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • filter

        public Option<E> filter​(ExecutionContext ctx,
                        FunctionDefinition test)
        Filter operation using Protelis functions.
        Parameters:
        ctx - ExecutionContext the execution context
        test - the function used as predicate. Must return boolean.
        Returns:
        If the test passes, the Option is unchanged. Otherwise, it's emptied.

      • filter

        public Option<E> filter​(java.util.function.Predicate<? super E> test)
        Parameters:
        test - predicate to test
        Returns:
        an Option describing the value of this Option if a value is present and the value matches the given predicate, otherwise an empty Option
        See Also:
        Optional.filter(Predicate)

      • filterNot

        public Option<E> filterNot​(ExecutionContext ctx,
                           FunctionDefinition test)
        Inverse filter operation using Protelis functions.
        Parameters:
        ctx - ExecutionContext the execution context
        test - the function used as predicate. Must return boolean.
        Returns:
        If the test passes, the Option is emptied, otherwise, it's left unchanged.

      • filterNot

        public Option<E> filterNot​(java.util.function.Predicate<? super E> test)
        Inverse of filter(Predicate).
        Parameters:
        test - predicate to test
        Returns:
        an Option describing the value of this Option if a value is present and the value does not match the given predicate, otherwise an empty Option
        See Also:
        Optional.filter(Predicate)

      • flatMap

        public <X> Option<X> flatMap​(ExecutionContext ctx,
                             FunctionDefinition fun)
        Optional.flatMap(Function) function callable via Protelis.
        Type Parameters:
        X - The type parameter to the Optional returned
        Parameters:
        ctx - ExecutionContext
        fun - Function to run. Must accept a single parameter and return an Option, Optional, Optional, or a Java class with a get() method and one of the following methods isPresent(), isNotPresent(), isEmpty(), isAbsent():
        Returns:
        the result of applying an Optional-bearing mapping function to the value of this Optional, if a value is present, otherwise an empty Optional

      • flatMap

        public <X> Option<X> flatMap​(java.util.function.Function<? super E,​Option<X>> fun)
        Type Parameters:
        X - The type parameter to the Optional returned
        Parameters:
        fun - a mapping function to apply to the value, if present the mapping function
        Returns:
        the result of applying an Optional-bearing mapping function to the value of this Optional, if a value is present, otherwise an empty Optional
        See Also:
        Optional.flatMap(Function)

      • get

        public E get()
        Returns:
        the internal value of the Option, or a RuntimeException if absent.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • isAbsent

        public boolean isAbsent()
        Returns:
        true if the Option has no value

      • isEmpty

        public boolean isEmpty()
        Returns:
        true if the Option has no value

      • isPresent

        public boolean isPresent()
        Returns:
        true if the Option is holding a value

      • map

        public Option<java.lang.Object> map​(ExecutionContext ctx,
                                    FunctionDefinition mapper)
        Parameters:
        ctx - ExecutionContext
        mapper - a mapping function to apply to the value, if present
        Returns:
        an Option describing the result of applying a mapping function to the value of this Option, if a value is present, otherwise an empty Option.

      • map

        public <X> Option<X> map​(java.util.function.Function<? super E,​? extends X> mapper)
        Type Parameters:
        X - The type of the result of the mapping function
        Parameters:
        mapper - a mapping function to apply to the value, if present
        Returns:
        an Option describing the result of applying a mapping function to the value of this Option, if a value is present, otherwise an empty Option
        See Also:
        Optional.map(Function)

      • merge

        public Option<E> merge​(Option<E> other,
                       java.util.function.BinaryOperator<E> combiner)
        If both options are present, the combiner function is executed on the Option contents. Otherwise, if an Option is present, it is returned. Finally, if both are empty, an empty Option is returned.
        Parameters:
        other - the other option
        combiner - the combining (reduction) function
        Returns:
        Option.of(combiner(this.get(), other.get()) if both are present, the only present option iff one is present, an empty option otherwise

      • or

        public Option<? extends E> or​(java.util.Optional<? extends E> other)
        Return the value if present, otherwise return other.
        Parameters:
        other - alternative
        Returns:
        this Optional if it has a value present; other otherwise.

      • or

        public Option<? extends E> or​(Option<? extends E> other)
        Return the value if present, otherwise return other.
        Parameters:
        other - alternative
        Returns:
        this Optional if it has a value present; other otherwise.

      • or

        public Option<? extends E> or​(com.google.common.base.Optional<? extends E> other)
        Return the value if present, otherwise return other.
        Parameters:
        other - alternative
        Returns:
        this Optional if it has a value present; other otherwise.

      • orElse

        public E orElse​(E other)
        Return the value if present, otherwise return other.
        Parameters:
        other - the value to be returned if there is no value present
        Returns:
        the value, if present, otherwise other

      • orElseGet

        public E orElseGet​(ExecutionContext ctx,
                   FunctionDefinition other)
        Return the value if present, otherwise invoke other and return the result of that invocation.
        Parameters:
        ctx - ExecutionContext
        other - a 0-ary protelis function
        Returns:
        the value if present otherwise the result of other.get()

      • orElseGet

        public E orElseGet​(java.util.function.Supplier<? extends E> other)
        Return the value if present, otherwise invoke other and return the result of that invocation.
        Parameters:
        other - a Supplier whose result is returned if no value is present
        Returns:
        the value if present otherwise the result of other.get()

      • orElseThrow

        public <X extends java.lang.RuntimeException> E orElseThrow​(java.util.function.Supplier<? extends X> exceptionSupplier)
        Return the contained value, if present, otherwise throw an exception to be created by the provided supplier.
        Type Parameters:
        X - Type of the exception to be thrown
        Parameters:
        exceptionSupplier - The supplier which will return the exception to be thrown
        Returns:
        the present value

      • toGuava

        public com.google.common.base.Optional<E> toGuava()
        Returns:
        a Guava compatible view of this Option

      • toJavaUtil

        public java.util.Optional<E> toJavaUtil()
        Returns:
        a Optional view of this Option

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • transform

        public Option<java.lang.Object> transform​(ExecutionContext ctx,
                                          FunctionDefinition mapper)
        Parameters:
        ctx - ExecutionContext
        mapper - a mapping function to apply to the value, if present
        Returns:
        an Option describing the result of applying a mapping function to the value of this Option, if a value is present, otherwise an empty Option.

      • transform

        public <X> Option<X> transform​(java.util.function.Function<? super E,​? extends X> mapper)
        Type Parameters:
        X - The type of the result of the mapping function
        Parameters:
        mapper - a mapping function to apply to the value, if present
        Returns:
        an Option describing the result of applying a mapping function to the value of this Option, if a value is present, otherwise an empty Option
        See Also:
        Optional.map(Function)

      • absent

        public static <E> Option<E> absent()
        Returns an empty Option instance. No value is present for this Optional.
        Type Parameters:
        E - Type of the non-existent value
        Returns:
        an empty Option

      • empty

        public static <E> Option<E> empty()
        Returns an empty Option instance. No value is present for this Optional.
        Type Parameters:
        E - Type of the non-existent value
        Returns:
        an empty Option

      • fromGuava

        public static <E> Option<E> fromGuava​(com.google.common.base.Optional<E> origin)
        Type Parameters:
        E - option type
        Parameters:
        origin - the guava Optional
        Returns:
        a Protelis view of the Guava Option

      • fromJavaUtil

        public static <E> Option<E> fromJavaUtil​(java.util.Optional<E> origin)
        Type Parameters:
        E - option type
        Parameters:
        origin - the Java Optional
        Returns:
        a Protelis view of the Java Option

      • fromNullable

        public static <E> Option<E> fromNullable​(E value)
        Returns an Option describing the specified value, if non-null, otherwise returns an empty Option.
        Type Parameters:
        E - the class of the value
        Parameters:
        value - the possibly-null value to describe
        Returns:
        an Option with a present value if the specified value is non-null, otherwise an empty Option

      • of

        public static <E> Option<E> of​(E value)
        Returns an Option describing the specified value, if non-null, otherwise returns an empty Option.
        Type Parameters:
        E - the class of the value
        Parameters:
        value - the possibly-null value to describe
        Returns:
        an Option with a present value if the specified value is non-null, otherwise an empty Option

      • ofNullable

        public static <E> Option<E> ofNullable​(E value)
        Returns an Option describing the specified value, if non-null, otherwise returns an empty Option.
        Type Parameters:
        E - the class of the value
        Parameters:
        value - the possibly-null value to describe
        Returns:
        an Option with a present value if the specified value is non-null, otherwise an empty Option