com.annimon.stream

Class Optional<T>

java.lang.Object

com.annimon.stream.Optional<T>

Type Parameters:

T - the type of the inner value

public class Optional<T>
extends java.lang.Object

A container object which may or may not contain a non-null value.

Method Summary

Modifier and Type	Method and Description
<R> R	custom(Function<Optional<T>,R> function) Applies custom operator on Optional.
static <T> Optional<T>	empty() Returns an empty Optional.
boolean	equals(java.lang.Object obj)
Optional<T>	executeIfAbsent(java.lang.Runnable action) Invokes action function if value is absent.
Optional<T>	executeIfPresent(Consumer<? super T> consumer) Invokes consumer function with the value if present.
Optional<T>	filter(Predicate<? super T> predicate) Performs filtering on inner value if it is present.
Optional<T>	filterNot(Predicate<? super T> predicate) Performs negated filtering on inner value if it is present.
<U> Optional<U>	flatMap(Function<? super T,Optional<U>> mapper) Invokes mapping function with Optional result if value is present.
T	get() Returns an inner value if present, otherwise throws NoSuchElementException.
int	hashCode()
void	ifPresent(Consumer<? super T> consumer) Invokes consumer function with value if present.
void	ifPresentOrElse(Consumer<? super T> consumer, java.lang.Runnable emptyAction) If a value is present, performs the given action with the value, otherwise performs the given empty-based action.
boolean	isEmpty() Checks the value is not present.
boolean	isPresent() Checks value present.
<U> Optional<U>	map(Function<? super T,? extends U> mapper) Invokes the given mapping function on inner value if present.
OptionalBoolean	mapToBoolean(ToBooleanFunction<? super T> mapper) Invokes mapping function on inner value if present.
OptionalDouble	mapToDouble(ToDoubleFunction<? super T> mapper) Invokes mapping function on inner value if present.
OptionalInt	mapToInt(ToIntFunction<? super T> mapper) Invokes the given mapping function on inner value if present.
OptionalLong	mapToLong(ToLongFunction<? super T> mapper) Invokes mapping function on inner value if present.
static <T> Optional<T>	of(T value) Returns an Optional with the specified present non-null value.
static <T> Optional<T>	ofNullable(T value) Returns an Optional with the specified value, or empty Optional if value is null.
Optional<T>	or(Supplier<Optional<T>> supplier) Returns current Optional if value is present, otherwise returns an Optional produced by supplier function.
T	orElse(T other) Returns inner value if present, otherwise returns other.
T	orElseGet(Supplier<? extends T> other) Returns inner value if present, otherwise returns value produced by supplier function.
T	orElseThrow() Returns inner value if present, otherwise throws NoSuchElementException.
<X extends java.lang.Throwable> T	orElseThrow(Supplier<? extends X> exc) Returns inner value if present, otherwise throws the exception provided by supplier function.
<R> Optional<R>	select(java.lang.Class<R> clazz) Keeps inner value only if is present and instance of given class.
Stream<T>	stream() Wraps a value into Stream if present, otherwise returns an empty Stream.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

of

@NotNull
 @Contract(value="_ -> new")
public static <T> Optional<T> of(@NotNull
                                                                       T value)

Returns an Optional with the specified present non-null value.

Type Parameters:

T - the type of value

Parameters:

value - the value to be present, must be non-null

Returns:

an Optional

Throws:

java.lang.NullPointerException - if value is null

See Also:

ofNullable(java.lang.Object)

ofNullable

@NotNull
public static <T> Optional<T> ofNullable(@Nullable
                                                  T value)

Returns an Optional with the specified value, or empty Optional if value is null.

Type Parameters:

T - the type of value

Parameters:

value - the value which can be null

Returns:

an Optional

See Also:

of(java.lang.Object)

empty

@NotNull
 @Contract(pure=true)
public static <T> Optional<T> empty()

Returns an empty Optional.

Type Parameters:

T - the type of value

Returns:

an Optional

get

@NotNull
public T get()

Returns an inner value if present, otherwise throws NoSuchElementException. Since 1.2.0 prefer orElseThrow() method as it has readable name.

Returns:

the inner value of Optional

Throws:

java.util.NoSuchElementException - if value is not present

See Also:

orElseThrow()

isPresent

public boolean isPresent()

Checks value present.

Returns:

true if a value present, false otherwise

isEmpty

public boolean isEmpty()

Checks the value is not present.

Returns:

true if a value is not present, false otherwise

Since:

1.2.1

ifPresent

public void ifPresent(@NotNull
                      Consumer<? super T> consumer)

Invokes consumer function with value if present.

Parameters:

consumer - the consumer function

ifPresentOrElse

public void ifPresentOrElse(@NotNull
                            Consumer<? super T> consumer,
                            @NotNull
                            java.lang.Runnable emptyAction)

If a value is present, performs the given action with the value, otherwise performs the given empty-based action.

Parameters:

consumer - the consumer function to be executed, if a value is present

emptyAction - the empty-based action to be performed, if no value is present

Throws:

java.lang.NullPointerException - if a value is present and the given consumer function is null, or no value is present and the given empty-based action is null.

executeIfPresent

@NotNull
public Optional<T> executeIfPresent(@NotNull
                                             Consumer<? super T> consumer)

Invokes consumer function with the value if present. This method same as ifPresent, but does not breaks chaining

Parameters:

consumer - consumer function

Returns:

this Optional

Since:

1.1.2

See Also:

ifPresent(com.annimon.stream.function.Consumer)

executeIfAbsent

@NotNull
public Optional<T> executeIfAbsent(@NotNull
                                            java.lang.Runnable action)

Invokes action function if value is absent.

Parameters:

action - action that invokes if value absent

Returns:

this Optional

Since:

1.1.2

custom

@Nullable
public <R> R custom(@NotNull
                              Function<Optional<T>,R> function)

Applies custom operator on Optional.

Type Parameters:

R - the type of the result

Parameters:

function - a transforming function

Returns:

a result of the transforming function

Throws:

java.lang.NullPointerException - if function is null

Since:

1.1.9

filter

@NotNull
public Optional<T> filter(@NotNull
                                   Predicate<? super T> predicate)

Performs filtering on inner value if it is present.

Parameters:

predicate - a predicate function

Returns:

this Optional if the value is present and matches predicate, otherwise an empty Optional

filterNot

@NotNull
public Optional<T> filterNot(@NotNull
                                      Predicate<? super T> predicate)

Performs negated filtering on inner value if it is present.

Parameters:

predicate - a predicate function

Returns:

this Optional if the value is present and doesn't matches predicate, otherwise an empty Optional

Since:

1.1.9

map

@NotNull
public <U> Optional<U> map(@NotNull
                                    Function<? super T,? extends U> mapper)

Invokes the given mapping function on inner value if present.

Type Parameters:

U - the type of result value

Parameters:

mapper - mapping function

Returns:

an Optional with transformed value if present, otherwise an empty Optional

Throws:

java.lang.NullPointerException - if value is present and mapper is null

mapToInt

@NotNull
public OptionalInt mapToInt(@NotNull
                                     ToIntFunction<? super T> mapper)

Invokes the given mapping function on inner value if present.

Parameters:

mapper - mapping function

Returns:

an OptionalInt with transformed value if present, otherwise an empty OptionalInt

Throws:

java.lang.NullPointerException - if value is present and mapper is null

Since:

1.1.3

mapToLong

@NotNull
public OptionalLong mapToLong(@NotNull
                                       ToLongFunction<? super T> mapper)

Invokes mapping function on inner value if present.

Parameters:

mapper - mapping function

Returns:

an OptionalLong with transformed value if present, otherwise an empty OptionalLong

Throws:

java.lang.NullPointerException - if value is present and mapper is null

Since:

1.1.4

mapToDouble

@NotNull
public OptionalDouble mapToDouble(@NotNull
                                           ToDoubleFunction<? super T> mapper)

Invokes mapping function on inner value if present.

Parameters:

mapper - mapping function

Returns:

an OptionalDouble with transformed value if present, otherwise an empty OptionalDouble

Throws:

java.lang.NullPointerException - if value is present and mapper is null

Since:

1.1.4

mapToBoolean

@NotNull
public OptionalBoolean mapToBoolean(@NotNull
                                             ToBooleanFunction<? super T> mapper)

Invokes mapping function on inner value if present.

Parameters:

mapper - mapping function

Returns:

an OptionalBoolean with transformed value if present, otherwise an empty OptionalBoolean

Throws:

java.lang.NullPointerException - if value is present and mapper is null

flatMap

@NotNull
public <U> Optional<U> flatMap(@NotNull
                                        Function<? super T,Optional<U>> mapper)

Invokes mapping function with Optional result if value is present.

Type Parameters:

U - the type of result value

Parameters:

mapper - mapping function

Returns:

an Optional with transformed value if present, otherwise an empty Optional

stream

@NotNull
public Stream<T> stream()

Wraps a value into Stream if present, otherwise returns an empty Stream.

Returns:

the optional value as a Stream

select

@NotNull
public <R> Optional<R> select(@NotNull
                                       java.lang.Class<R> clazz)

Keeps inner value only if is present and instance of given class.

Type Parameters:

R - a type of instance to select.

Parameters:

clazz - a class which instance should be selected

Returns:

an Optional with value of type class if present, otherwise an empty Optional

or

@NotNull
public Optional<T> or(@NotNull
                               Supplier<Optional<T>> supplier)

Returns current Optional if value is present, otherwise returns an Optional produced by supplier function.

Parameters:

supplier - supplier function that produces an Optional to be returned

Returns:

this Optional if value is present, otherwise an Optional produced by supplier function

Throws:

java.lang.NullPointerException - if value is not present and supplier or value produced by it is null

orElse

@Nullable
public T orElse(@Nullable
                          T other)

Returns inner value if present, otherwise returns other.

Parameters:

other - the value to be returned if inner value is not present

Returns:

inner value if present, otherwise other

orElseGet

@Nullable
public T orElseGet(@NotNull
                             Supplier<? extends T> other)

Returns inner value if present, otherwise returns value produced by supplier function.

Parameters:

other - supplier function that produces value if inner value is not present

Returns:

inner value if present, otherwise value produced by supplier function

orElseThrow

@NotNull
public T orElseThrow()

Returns inner value if present, otherwise throws NoSuchElementException.

Returns:

inner value if present

Throws:

java.util.NoSuchElementException - if inner value is not present

Since:

1.2.0

orElseThrow

@NotNull
public <X extends java.lang.Throwable> T orElseThrow(@NotNull
                                                              Supplier<? extends X> exc)
                                                       throws X extends java.lang.Throwable

Returns inner value if present, otherwise throws the exception provided by supplier function.

Type Parameters:

X - the type of exception to be thrown

Parameters:

exc - supplier function that produces an exception to be thrown

Returns:

inner value if present

Throws:

X - if inner value is not present

X extends java.lang.Throwable

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

@NotNull
public java.lang.String toString()

Overrides:

toString in class java.lang.Object