> ## 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 - The Safety Net

> Your collections deserve protection. Use null-aware extensions to access list ends and indices without ever crashing your app with a RangeError or StateError.

<Steps titleSize="h3">
  <Step title="🔝 Ends of the List">
    <ResponseField name="firstOrNull" type="T?">
      Gets the first element of the list, or returns `null` if the list is empty. Prevents `StateError`.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final numbers = [1, 2, 3];
      final result = numbers.firstOrNull;  // 1

      final alphabets = [];
      final last = alphabets.firstOrNull; // null
      ```
    </ResponseField>

    <ResponseField name="lastOrNull" type="T?">
      Gets the last element of the list, or returns `null` if the list is empty. Prevents `StateError`.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final names = ['Alice', 'Bob'];
      final last = names.lastOrNull; // 'Bob'

      final ids = [];
      final last = ids.lastOrNull; // null
      ```
    </ResponseField>
  </Step>

  <Step title="🔍 Index & Element Access">
    <ResponseField name="elementAtOrNull(int index)" type="T?">
      <Expandable title="Parameters">
        <ParamField body="index" type="int" required>
          The zero-based index of the element to retrieve.
        </ParamField>
      </Expandable>

      Safely retrieves an element at a given `index`, returning `null` if the `index` is out of bounds. Prevents `RangeError`.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final data = ['a', 'b', 'c'];
      final safe = data.elementAtOrNull(10); // null
      ```
    </ResponseField>

    <ResponseField name="indexOfOrNull(T element)" type="int?">
      <Expandable title="Parameters">
        <ParamField body="element" type="T" required>
          The element to locate in the list.
        </ParamField>
      </Expandable>

      Gets the `index` of the element, or returns `null` if the element doesn't exist in the list.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final ids = [10, 20, 30];
      final notFound = ids.indexOfOrNull(50); // null
      ```
    </ResponseField>

    <ResponseField name="firstWhereOrNull(bool Function(T) test)" type="T?">
      <Expandable title="Parameters">
        <ParamField body="test" type="bool Function(T)" required>
          A function that returns `true` for the element you are looking for.
        </ParamField>
      </Expandable>

      Gets the first element that satisfies the `test`, or returns `null` if none is found. Prevents `StateError` without needing an `orElse` callback.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final users = [{'id': 1}, {'id': 2}];
      final missing = users.firstWhereOrNull((u) => u['id'] == 99); // null
      ```
    </ResponseField>
  </Step>
</Steps>