# apfel.container.value

*module*

`apfel.container.value` provides a container that simply wraps a value
designed to aid chained method calls.

See also [:haskell `Identity`](https://hackage.haskell.org/package/base/docs/Data-Functor-Identity.html).

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L1-L1)

## apfel.container.value.Value

*class*

```python
class Value(Monad)
```

Bases: `apfel.core.monad.Monad`

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L11-L152)

### apfel.container.value.Value.__doc__

*attribute* · *instance attribute*

```python
__doc__ = value.__doc__
```

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L18-L18)

### apfel.container.value.Value.__slots__

*attribute* · *class attribute* · *instance attribute*

```python
__slots__ = ('_value')
```

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L12-L12)

### apfel.container.value.Value.__class_getitem__

*method*

```python
def __class_getitem__(item: type[U]) -> Value[U]
```

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L20-L21)

### apfel.container.value.Value.__init__

*method*

```python
def __init__(value: T)
```

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L14-L18)

### apfel.container.value.Value.__repr__

*method*

```python
def __repr__()
```

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L26-L27)

### apfel.container.value.Value.__str__

*method*

```python
def __str__()
```

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L23-L24)

### apfel.container.value.Value.apply

*method*

```python
def apply(func: Value[Callable[[T], R]], /) -> Value[R]
```

Apply a function wrapped inside a `Value` to the inner value.
Implementation of [`Applicative.apply`][apfel.core.monad.Applicative.apply].

**Parameters**

- `func` (`Value[Callable[[T], R]]`) — A `Value` containing a function to apply.

**Returns**

- (`Value[R]`) — Value[R]: A new `Value` containing the result of the function application.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L29-L40)

### apfel.container.value.Value.bind

*method*

```python
def bind(func: Callable[[T], Value[R]], /) -> Value[R]
```

Monadically bind a function that maps the inner value to a new `Value`.
Implementation of [`Monad.bind`][apfel.core.monad.Monad.bind].

**Parameters**

- `func` (`Callable[[T], Value[R]]`) — A function that takes the inner value and returns a `Value`.

**Returns**

- (`Value[R]`) — Value[R]: A new `Value` containing the result of the function.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L42-L53)

### apfel.container.value.Value.done

*method*

```python
def done() -> T
```

Return the value wrapped inside the container.

Unlike `unwrap` methods on other containers, this method will never raise
exceptions.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L55-L62)

### apfel.container.value.Value.map

*method*

```python
def map(func: Callable[[T], U], /) -> Value[U]
```

Map a function over the `Value` container. Implementation of [`Functor.map`][apfel.core.monad.Functor.map].

**Parameters**

- `func` (`Callable[[T], U]`) — A function to transform the inner value.

**Returns**

- (`Value[U]`) — Value[U]: A new `Value` containing the transformed value.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L64-L74)

### apfel.container.value.Value.mutate

*method*

```python
def mutate(func: Callable[[T], Any], /) -> Self
```

Call a function to mutate the inner value in place.

The function's return value is ignored, and the container keeps the
original inner reference.
This is similar to [`Value.tap`][apfel.container.value.Value.tap],
just hinting the mutating intention of the function.

**Parameters**

- `func` (`Callable[[T], Any]`) — A function that mutates the inner value.

**Returns**

- (`Self`) — Value[T]: The mutated container itself.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L76-L92)

### apfel.container.value.Value.pure

*method* · *classmethod*

```python
def pure(value: R | T, /) -> Value[R] | Value[T]
```

Wrap a value into the `Value` container.
Implementation of [`Applicative.pure`][apfel.core.monad.Applicative.pure].

**Parameters**

- `value` (`T`) — The value to wrap.

**Returns**

- (`Value[R] | Value[T]`) — Value[T]: A new instance of `Value` with the value wrapped.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L94-L106)

### apfel.container.value.Value.run

*method*

```python
def run(func: Callable[[T], R], /) -> R
```

Run a function to process the inner value, and return the result.

**Parameters**

- `func` (`Callable[[T], R]`) — A function to process the value.

**Returns**

- `R` (`R`) — The result of the function.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L108-L118)

### apfel.container.value.Value.tap

*method*

```python
def tap(func: Callable[[T], Any], /) -> Value[T]
```

Call a function over the inner value, ignore the return value,
and return the original container.

See also [:kotlin `also`](https://kotlinlang.org/docs/scope-functions.html#also).

> **Warning**
>
> Pragmatically, the function shouldn't mutate the inner value.
> Use the [`Value.mutate`][apfel.container.value.Value.mutate] method instead.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L120-L133)

### apfel.container.value.Value.update

*method*

```python
def update(func: Callable[[T], T], /) -> Self
```

Update the inner value with the result of a function.

> **Warning**
>
> Compare to [`Value.map`][apfel.container.value.Value.map], this method
> mutates the container in place. No new container is created.
> Therefore, the function must return a result of the same type as the
> previous inner type of the container.

**Parameters**

- `func` (`Callable[[T], T]`) — A function to transform the inner value.

**Returns**

- (`Self`) — Value[T]: The mutated container itself.

[View source](https://github.com/Yixuan-Wang/apfel/blob/main/src/apfel/container/value.py#L135-L152)