> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/vendor/sanmai/pipeline/docs/api/transformation.md).

# Transformation Methods

Transformation methods are used to modify the elements within a pipeline.

## `map()`

Transforms each element using a callback function. This is the most flexible transformation method, as the callback can return a single value or a `Generator` to yield multiple values.

**Signature**: `map(?callable $func = null): self`

* `$func`: The transformation function.

**Callback Signature**: `function(mixed $value): mixed|Generator`

**Behavior**:

* If the callback returns a `Generator`, `map()` will expand it, yielding each of its values into the main pipeline.

> **Performance Note**
>
> When starting with an array, `map()` processes lazily but other methods in your chain might not. For large datasets, consider using `->stream()` first to ensure all operations process one element at a time, avoiding high memory usage.

**Examples**:

```php
// 1-to-1 transformation
$result = take([1, 2, 3])
    ->map(fn($x) => $x * 2)
    ->toList(); // [2, 4, 6]

// 1-to-many transformation with a generator
$result = take(['a', 'b'])
    ->map(function ($char) {
        yield $char;
        yield strtoupper($char);
    })
    ->toList(); // ['a', 'A', 'b', 'B']
```

## `cast()`

Transforms each element using a callback, but with a key difference from `map()`: it does not expand generators. This makes it ideal for simple, 1-to-1 transformations, especially on arrays, where it is highly optimized.

**Signature**: `cast(?callable $func = null): self`

* `$func`: The transformation function.

**Behavior**:

* If the callback returns a `Generator`, `cast()` will treat it as a single value, not expand it.
* It is faster than `map()` for simple transformations on arrays because it uses `array_map()` internally.

> **Performance Note**
>
> When working with arrays, `cast()` uses PHP's `array_map()` internally, creating a new array in memory. For large datasets, use `->stream()` first to process elements one at a time.

**Examples**:

```php
// Type casting
$result = take(['1', '2', '3'])
    ->cast(intval(...))
    ->toList(); // [1, 2, 3]

// Creating a pipeline of generators
$result = take(['a', 'b'])
    ->cast(function ($char) {
        return (function () use ($char) {
            yield $char;
        })();
    })
    ->toList(); // [Generator, Generator]
```

## `flatten()`

Flattens a nested pipeline by one level.

**Signature**: `flatten(): self`

**Examples**:

```php
$result = take([[1, 2], [3, 4]])
    ->flatten()
    ->toList(); // [1, 2, 3, 4]
```

## `unpack()`

Unpacks array elements as arguments to a callback function.

**Signature**: `unpack(?callable $func = null): self`

* `$func`: The callback to receive the unpacked arguments.

**Behavior**:

* If no callback is provided, it behaves like `flatten()`.

**Examples**:

```php
$result = take([[1, 2], [3, 4]])
    ->unpack(fn($a, $b) => $a + $b)
    ->toList(); // [3, 7]
```

## `chunk()`

Splits the pipeline into chunks of a specified size.

**Signature**: `chunk(int $length, bool $preserve_keys = false): self`

* `$length`: The size of each chunk.
* `$preserve_keys`: Whether to preserve the original keys.

**Examples**:

```php
$result = take([1, 2, 3, 4, 5])
    ->chunk(2)
    ->toList(); // [[1, 2], [3, 4], [5]]
```

## `slice()`

Extracts a portion of the pipeline.

**Signature**: `slice(int $offset, ?int $length = null): self`

* `$offset`: The starting position.
* `$length`: The number of elements to extract.

**Examples**:

```php
$result = take([1, 2, 3, 4, 5])
    ->slice(1, 3)
    ->toList(); // [2, 3, 4]
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/vendor/sanmai/pipeline/docs/api/transformation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.