optional

<Default Package>
Type optional < TYPE >

Type Parameters:: TYPE - Contained type

Values which may be empty or have a value.

Values of the optional type contain either a value (of type TYPE) or are empty and thus have no value. This is useful for mapping to null values in other languages such as Java, or for data which may not be present in some circumstances.

An optional is either empty or contains a single value. The type of the value is specified between angle brackets in the optional type name and is known as the contained type. You can use the value from an optional in the following ways:

The recommended way is with the ifpresent statement. This is safest and makes it clear what happens if an optional is empty or not.
With instance methods. You can use getOrThrow or getOr methods to access the value.

Optional types are comparable provided the contained type is comparable. (Thus you can compare them equal, or sort them, provided the contained type supports those operations). When sorting, an empty optional is always less than an optional with a value.

Optionals cannot contain types of context, listener, stream, chunk, optional, any or action. All of these types may themselves be empty and thus do not need to be wrapped with optional. They can all be used by the ifpresent statement as well.

Example:

optional is useful when describing events that have data that may be unavailable. For example, an event describing the position of a smartphone may have several optional fields, depending on which mechanisms have been able to determine the position:

event GPSPosition { 
      float longitude; 
      float latitude; 
      float accuracy; 
      integer numSatFix; 
} 
 
event SmartPhonePosition { 
      string deviceId; 
      float timestamp; 
      optional<GPSPosition> gps; 
      optional<string> nearestCellId; 
      optional<sequence<string>> nearestWiFiMacAddresses; 
}

This event could distinguish between a GPS fix (in which case all of the members of GPSPosition are available and should be valid) and no GPS fix, and a nearest mobile phone cell or no cells being in range. Also note how it can distinguish between Wi-Fi switched on but no networks in range (non-empty optional containing a zero-length sequence) and Wi-Fi switched off (an empty optional). The deviceId and timestamp are always available in the SmartPhonePosition event.

The syntax for optional is:

optional<TYPE> varname

For example:

// An optional that may or may not contain an integer 
optional<integer> myOptInt;

The default value of an optional is an empty value. There is a single argument constructor:

optional<integer> myOptInt := optional<integer>(5);

But it is also possible to assign a variable or literal of type TYPE to an optional<TYPE>. For example:

optional<integer> myOptInt := 5;

See the documentation of the different types for detailed information on how to declare the literals.

An optional variable can potentially contain a cyclic type — a type that directly or indirectly refers to itself.

Action summary
`boolean`	`static` `canParse(string s)` Check if the string argument can be successfully parsed as an optional.
`optional<TYPE>`	`static` `parse(string s)` Parse a string as an optional.
`optional<TYPE>`	`clone()` Create a deep copy of this optional.
`boolean`	`empty()` Check if this optional has a value (this is a legacy alias for the `isEmpty()` method).
`TYPE`	`getOr(TYPE default)` Get the value of this optional or a specified default.
`TYPE`	`getOrThrow()` Get the value of this optional.
`integer`	`hash()` Get an integer hash representation of the underlying object.
`boolean`	`isEmpty()` Check if this optional has a value.
`string`	`toString()` Convert this optional to a string.

Action detail

canParse

boolean static canParse(string s)

Check if the string argument can be successfully parsed as an optional.

Parameters:: s - The string to test for parseability.

Returns:: True if the string could be parsed as an optional of this type, false otherwise.

See Also:: - See the parse method for how optionals are parsed.

parse

optional<TYPE> static parse(string s)

Parse a string as an optional.

The string form of an optional is:

optional(VALUE)

where VALUE is the string form of the value, or nothing if empty. For example optional(123.4), optional("my string") or optional().

Parameters:: s - The string to parse.

Returns:: The optional corresponding to the string.

Throws:: Throws ParseException if the argument cannot be parsed as this form of optional.

See Also:: - Use canParse() to check whether the string can be parsed without throwing.

clone

optional<TYPE> clone()

Create a deep copy of this optional.

This will copy the underlying value as well.

Returns:: A copy of this optional and its value (if any).

empty

boolean empty()

Check if this optional has a value (this is a legacy alias for the isEmpty() method).

Returns:: True if the optional is empty, false if it has a value (even if the contained object is itself an empty string, sequence, optional etc).

See Also:: - The recommended way to call this.; com.apama.functional.Fn.isEmpty() - To perform a deep detection for whether an any contains a value that itself is not empty.

getOr

TYPE getOr(TYPE default)

Get the value of this optional or a specified default.

Parameters:: default - The value to return if the optional is empty.

Returns:: The value of this optional, or default if it is empty.

getOrThrow

TYPE getOrThrow()

Get the value of this optional.

Returns:: The value of this optional.

Throws:: Throws NullPointerException if this optional is empty.

hash

integer hash()

Get an integer hash representation of the underlying object.

This function will return an integer evenly distributed over the whole range suitable for partitioning or indexing of that structure. Multiple different object can resolve to the same hash value.

If TYPE is not hashable, optional does not have a hash method.

Returns:: An integer respresentation of the underlying object.

isEmpty

boolean isEmpty()

Check if this optional has a value.

Returns:: True if the optional is empty, false if it has a value (even if the contained object is itself an empty string, sequence, optional etc).

Since:: 10.15.4.0

See Also:: com.apama.functional.Fn.isEmpty() - To perform a deep detection for whether an any contains a value that itself is not empty.

toString

string toString()

Convert this optional to a string.

Returns:: The string form of this optional.

See Also:: - See the parse method for the string form of an optional.

<Default Package>Type optional < TYPE >