> ## 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.

# String - Transformation & Utilities

> Essential string manipulation for padding, prefix/suffix ensuring, URL encoding, and masking sensitive data. Includes a null-safe extension.

<Steps titleSize="h3">
  <Step title="🛡️ Null-Safety (String?)">
    <ResponseField name="withDefaultValue(String defaultValue)" type="String">
      <Expandable title="Parameters">
        <ParamField body="defaultValue" type="String" required>
          The string to return if the original string is `null` or `empty`.
        </ParamField>
      </Expandable>

      Returns the original string if it is not `null` and `not empty`, otherwise returns the provided defaultValue. Guarantees a `non-null`, non-empty result.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      String? title = getTitleFromAPI();
      print(title.withDefaultValue('Untitled Document'));
      ```
    </ResponseField>
  </Step>

  <Step title="🔒 Security & Encoding">
    <ResponseField name="mask({int visibleCount, String maskCharacter})" type="String">
      <Expandable title="Parameters">
        <ParamField body="visibleCount" type="int" default="2">
          The number of characters to keep visible at the `start` and `end`.
        </ParamField>

        <ParamField body="maskCharacter" type="String" default="*">
          The `character` used to hide the central portion.
        </ParamField>
      </Expandable>

      Masks the central portion of the string while keeping a fixed number of characters visible at the beginning and end. Essential for sensitive data.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final card = '1234567890123456';
      print(card.mask(visibleCount: 4)); // "1234********3456"
      ```
    </ResponseField>

    <ResponseField name="withUrlEncoded()" type="String">
      `URL-encodes` the string, replacing illegal or unsafe characters (e.g., spaces) with percent-encoded equivalents.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final urlParam = 'user name'.withUrlEncoded(); // "user%20name"
      ```
    </ResponseField>
  </Step>

  <Step title="🔗 Boundaries & Wrapping">
    <ResponseField name="ensureEndsWith(String suffix)" type="String">
      <Expandable title="Parameters">
        <ParamField body="suffix" type="String" required>
          The `suffix` to ensure the string ends with.
        </ParamField>
      </Expandable>

      Ensures that the string ends with the specified `suffix`. The suffix is appended only if the string is not empty and does not already end with it.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      print('user'.ensureEndsWith('.json'));    // "user.json"
      ```
    </ResponseField>

    <ResponseField name="ensureStartsWith(String prefix)" type="String">
      <Expandable title="Parameters">
        <ParamField body="prefix" type="String" required>
          The `prefix` to ensure the string starts with.
        </ParamField>
      </Expandable>

      Ensures that the string starts with the specified `prefix`. The prefix is prepended only if the string is not empty and does not already start with it.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      print('data'.ensureStartsWith('/api/')); // "/api/data"
      ```
    </ResponseField>

    <ResponseField name="withBrackets([String left, String right])" type="String">
      <Expandable title="Parameters">
        <ParamField body="left" type="String" default="(">
          The opening delimiter.
        </ParamField>

        <ParamField body="right" type="String" default=")">
          The closing delimiter.
        </ParamField>
      </Expandable>

      Wraps the string with the specified left and right delimiters.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      print('success'.withBrackets('[', ']')); // "[success]"
      ```
    </ResponseField>

    <ResponseField name="withHashtag()" type="String">
      Prepends a `#` symbol and removes all spaces, formatting the string into a standardized hashtag.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      print('flutter extend'.withHashtag()); // "#flutterextend"
      ```
    </ResponseField>

    <ResponseField name="withEmoji(Emoji emoji)" type="String">
      <Expandable title="Parameters">
        <ParamField body="emoji" type="Emoji" required>
          The `Emoji` object containing the string representation of the emoji.
        </ParamField>
      </Expandable>

      Appends a graphical emoji representation to the end of the string, separated by a space.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      // Assuming Emoji.star is a defined constant
      print('Great Job'.withEmoji(Emoji.star)); // "Great Job ⭐"
      ```
    </ResponseField>
  </Step>

  <Step title="💯 Display & Utility">
    <ResponseField name="withOrdinal()" type="String">
      Converts a numeric string into its ordinal form (e.g., "1st", "2nd", "23rd"). Requires `isDigitsOnly()` to be available.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      print('11'.withOrdinal()); // "11th"
      print('23'.withOrdinal()); // "23rd"
      ```
    </ResponseField>

    <ResponseField name="withEllipsis(int maxLength)" type="String">
      <Expandable title="Parameters">
        <ParamField body="maxLength" type="int" required>
          The `maximum` number of characters allowed before truncation.
        </ParamField>
      </Expandable>

      Truncates the string if its length exceeds `maxLength` and appends an ellipsis ("...").

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final long = 'This is a long message';
      print(long.withEllipsis(10)); // "This is a ..."
      ```
    </ResponseField>

    <ResponseField name="truncateName()" type="String">
      Truncates a full name (first and last name) to show the first name and the initial of the last name (e.g., "John D.").

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final name1 = 'Alice Wonderland';
      print(name1.truncateName()); // "Alice W."
      ```
    </ResponseField>

    <ResponseField name="reverse()" type="String">
      Reverses the order of the characters in the string.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final text = 'dart';
      print(text.reverse()); // "trad"
      ```
    </ResponseField>

    <ResponseField name="getLastNCharacters(int n)" type="String">
      <Expandable title="Parameters">
        <ParamField body="n" type="int" required>
          The `number` of characters to retrieve from the `end` of the string.
        </ParamField>
      </Expandable>

      Retrieves the `last N` characters of the `string`.

      ```dart lines wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      final id = 'TX202512345';
      print(id.getLastNCharacters(4)); // "2345"
      ```
    </ResponseField>
  </Step>
</Steps>