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

# List/Iterable - Transformations & Sorting

> Functional utilities for complex list mapping, efficient sorting by property (selector), chunking for pagination, and creating shuffled copies.

<Steps titleSize="h3">
  <Step title="🗺️ Mapping & Filtering">
    <ResponseField name="mapIndexed<R>(R Function(int index, T item) mapper)" type="List<R>">
      <Expandable title="Parameters">
        <ParamField body="mapper" type="R Function(int index, T item)" required>
          A function that accepts the index and the item, returning a new value.
        </ParamField>
      </Expandable>

      Maps the list, providing the element's index along with the item to the `mapper function`. Perfect for generating indexed widgets.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final names = ['Alice', 'Bob'];
      final widgets = names.mapIndexed((i, name) => Text('No. $i: $name'));
      ```
    </ResponseField>

    <ResponseField name="mapNotNull<R>(R? Function(T item) mapper)" type="List<R>">
      <Expandable title="Parameters">
        <ParamField body="mapper" type="R? Function(T item)" required>
          A function that transforms the item into a potentially nullable value.
        </ParamField>
      </Expandable>

      Maps the list and automatically filters out all resulting `null` values, guaranteeing a non-nullable output list.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final grades = [85, 40];
      final passing = grades.mapNotNull((g) => g >= 50 ? g : null); // [85]
      ```
    </ResponseField>
  </Step>

  <Step title="🔄 Sorting & Order">
    <ResponseField name="reversedList" type="List<T>">
      Gets a **new list** containing the elements of the original list in reverse order.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final original = [1, 2, 3];
      final reversed = original.reversedList; // [3, 2, 1]
      ```
    </ResponseField>

    <ResponseField name="sortBy(Comparable Function(T) selector, {bool ascending})" type="void">
      <Expandable title="Parameters">
        <ParamField body="selector" type="Comparable Function(T)" required>
          A function that returns a `Comparable` property (e.g., `int`, `String`) by which to sort.
        </ParamField>

        <ParamField body="ascending" type="bool" default="true">
          If `true`, sorts from smallest to largest; otherwise, largest to smallest.
        </ParamField>
      </Expandable>

      Sorts the list **in-place** (mutates the original list) based on a selected property.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      // Sorts by score in ascending order (10, 20)
      users.sortBy((user) => user.score);
      ```

      <Note>
        Mutates the original list
      </Note>
    </ResponseField>

    <ResponseField name="sortByAndReturnSorted(Comparable Function(T) selector, {bool ascending})" type="List<T>">
      <Expandable title="Parameters">
        <ParamField body="selector" type="Comparable Function(T)" required>
          A function that returns a `Comparable` property (e.g., `int`, `String`) by which to sort.
        </ParamField>

        <ParamField body="ascending" type="bool" default="true">
          If `true`, sorts from smallest to largest; otherwise, largest to smallest.
        </ParamField>
      </Expandable>

      Sorts the list based on a selected property and **returns a new sorted list**. The original list remains unchanged.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final originalScores = [10, 50, 20];
      final topScores = originalScores.sortByAndReturnSorted((s) => s, ascending: false);
      ```

      <Note>
        Returns a new sorted list. The original list remains unchanged.
      </Note>
    </ResponseField>
  </Step>

  <Step title="✂️ Structural Changes">
    <ResponseField name="chunked(int chunkSize)" type="List<List<T>>">
      <Expandable title="Parameters">
        <ParamField body="chunkSize" type="int" required>
          The maximum size for each chunk. Must be greater than 0.
        </ParamField>
      </Expandable>

      Splits the list into smaller sub-lists (chunks) of a maximum specified size. Highly useful for pagination or multi-column layouts.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final items = [1, 2, 3, 4, 5, 6, 7];
      final chunks = items.chunked(3); // "chunks is [[1, 2, 3], [4, 5, 6], [7]]"
      ```
    </ResponseField>
  </Step>
</Steps>