> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-dpm-import.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DA.Optional

> Reference documentation for Daml module DA.Optional.

<span id="module-da-optional-38505" />

# DA.Optional

The `Optional` type encapsulates an optional value. A value of type

`Optional a` either contains a value of type `a` (represented as `Some a`),

or it is empty (represented as `None`). Using `Optional` is a good way

to deal with errors or exceptional cases without resorting to

drastic measures such as error.

The Optional type is also an action. It is a simple kind of error

action, where all errors are represented by `None`. A richer

error action can be built using the `Either` type.

## Module Snapshot

<CardGroup cols={2}>
  <Card title="Lifecycle">
    Stable.
  </Card>

  <Card title="Notices">
    Status: `active`
    Introduced in: `3.4.9`
    Removed in: `-`
    Warnings: `0`
    Deprecations: `0`
    Deprecated since: `-`
  </Card>
</CardGroup>

## Functions

<span id="function-da-optional-fromsome-59859" />

### `fromSome`

`fromSome` : [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> `a`

The `fromSome` function extracts the element out of a `Some` and
throws an error if its argument is `None`.

Note that in most cases you should prefer using `fromSomeNote`
to get a better error on failures.

<span id="function-da-optional-fromsomenote-25463" />

### `fromSomeNote`

`fromSomeNote` : [`Text`](/appdev/reference/daml-standard-library/prelude#type-ghc-types-text-51952) -> [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> `a`

Like `fromSome` but with a custom error message.

<span id="function-da-optional-catoptionals-11568" />

### `catOptionals`

`catOptionals` : \[[`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a`] -> \[`a`]

The `catOptionals` function takes a list of `Optionals` and returns a
list of all the `Some` values.

<span id="function-da-optional-listtooptional-83598" />

### `listToOptional`

`listToOptional` : \[`a`] -> [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a`

The `listToOptional` function returns `None` on an empty list or
`Some` a where a is the first element of the list.

<span id="function-da-optional-optionaltolist-83426" />

### `optionalToList`

`optionalToList` : [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> \[`a`]

The `optionalToList` function returns an empty list when given
`None` or a singleton list when not given `None`.

<span id="function-da-optional-fromoptional-77879" />

### `fromOptional`

`fromOptional` : `a` -> [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> `a`

The `fromOptional` function takes a default value and a `Optional`
value. If the `Optional` is `None`, it returns the default values
otherwise, it returns the value contained in the `Optional`.

<span id="function-da-optional-issome-25261" />

### `isSome`

`isSome` : [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> [`Bool`](/appdev/reference/daml-standard-library/prelude#type-ghc-types-bool-66265)

The `isSome` function returns `True` iff its argument is of the
form `Some _`.

<span id="function-da-optional-isnone-84783" />

### `isNone`

`isNone` : [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> [`Bool`](/appdev/reference/daml-standard-library/prelude#type-ghc-types-bool-66265)

The `isNone` function returns `True` iff its argument is
`None`.

<span id="function-da-optional-mapoptional-4330" />

### `mapOptional`

`mapOptional` : (`a` -> [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `b`) -> \[`a`] -> \[`b`]

The `mapOptional` function is a version of `map` which can throw out
elements. In particular, the functional argument returns something
of type `Optional b`. If this is `None`, no element is added on to
the result list. If it is `Some b`, then `b` is included in the
result list.

<span id="function-da-optional-whensome-82167" />

### `whenSome`

`whenSome` : [`Applicative`](/appdev/reference/daml-standard-library/prelude#class-da-internal-prelude-applicative-9257) `m` => [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> (`a` -> `m` ()) -> `m` ()

Perform some operation on `Some`, given the field inside the
`Some`.

<span id="function-da-optional-whensome-5861" />

### `whenSome_`

`whenSome_` : [`Applicative`](/appdev/reference/daml-standard-library/prelude#class-da-internal-prelude-applicative-9257) `m` => [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> (`a` -> `m` `b`) -> `m` ()

Perform some operation on `Some` and discard its result,
given the field inside the `Some`.

<span id="function-da-optional-whennone-99309" />

### `whenNone`

`whenNone` : [`Applicative`](/appdev/reference/daml-standard-library/prelude#class-da-internal-prelude-applicative-9257) `m` => [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> `m` `a` -> `m` `a`

Perform some operation on `None`.
Otherwise returns content of `Some` pured to Applicative.

<span id="function-da-optional-whennone-43843" />

### `whenNone_`

`whenNone_` : [`Applicative`](/appdev/reference/daml-standard-library/prelude#class-da-internal-prelude-applicative-9257) `m` => [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `a` -> `m` `b` -> `m` ()

Perform some operation on `None`. Do nothing for `Some`.
Convenient for discarding `Some` content.

<span id="function-da-optional-findoptional-83634" />

### `findOptional`

`findOptional` : (`a` -> [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `b`) -> \[`a`] -> [`Optional`](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) `b`

The `findOptional` returns the value of the predicate at the first
element where it returns `Some`. `findOptional` is similar to `find` but it
allows you to return a value from the predicate. This is useful both as a more
type safe version if the predicate corresponds to a pattern match
and for performance to avoid duplicating work performed in the predicate.