optional

FRAMES NO FRAMES

Overview

Package

Deprecated

Help

API Reference for EPL (ApamaDoc) 10.11.3.3

SUMMARY: IMPORT | CONSTANT | MEMBER | ACTION

DETAIL: IMPORT | CONSTANT | MEMBER | ACTION

<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>`	`clone()` Create a deep copy of this optional.
`boolean`	`empty()` Check if this optional has a value.
`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.
`optional<TYPE>`	`static` `parse(string s)` Parse a string as an optional.
`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:: optional#parse() - See the parse method for how optionals are parsed.

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.

Returns:: True if the optional is empty, false if it has a value.

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.

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:: optional#canParse() - Use canParse() to check whether the string can be parsed without throwing.

toString

            string toString()

Convert this optional to a string.

Returns:: The string form of this optional.

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