String - Transformation & Utilities

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

1. 🛡️ Null-Safety (String?)

   withDefaultValue(String defaultValue) · String

   Show Parameters

   defaultValue · String · required

   The string to return if the original string is null or empty.

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

   String? title = getTitleFromAPI();
   print(title.withDefaultValue('Untitled Document'));
   
2. 🔒 Security & Encoding

   mask({int visibleCount, String maskCharacter}) · String

   Show Parameters

   visibleCount · int · default: "2"

   The number of characters to keep visible at the start and end.

   maskCharacter · String · default: "*"

   The character used to hide the central portion.

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

   final card = '1234567890123456';
   print(card.mask(visibleCount: 4)); // "1234********3456"
   

   withUrlEncoded() · String

   URL-encodes the string, replacing illegal or unsafe characters (e.g., spaces) with percent-encoded equivalents.

   final urlParam = 'user name'.withUrlEncoded(); // "user%20name"
   
3. 🔗 Boundaries & Wrapping

   ensureEndsWith(String suffix) · String

   Show Parameters

   suffix · String · required

   The suffix to ensure the string ends with.

   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.

   print('user'.ensureEndsWith('.json'));    // "user.json"
   

   ensureStartsWith(String prefix) · String

   Show Parameters

   prefix · String · required

   The prefix to ensure the string starts with.

   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.

   print('data'.ensureStartsWith('/api/')); // "/api/data"
   

   withBrackets([String left, String right]) · String

   Show Parameters

   left · String · default: "("

   The opening delimiter.

   right · String · default: ")"

   The closing delimiter.

   Wraps the string with the specified left and right delimiters.

   print('success'.withBrackets('[', ']')); // "[success]"
   

   withHashtag() · String

   Prepends a # symbol and removes all spaces, formatting the string into a standardized hashtag.

   print('flutter extend'.withHashtag()); // "#flutterextend"
   

   withEmoji(Emoji emoji) · String

   Show Parameters

   emoji · Emoji · required

   The Emoji object containing the string representation of the emoji.

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

   // Assuming Emoji.star is a defined constant
   print('Great Job'.withEmoji(Emoji.star)); // "Great Job ⭐"
   
4. 💯 Display & Utility

   withOrdinal() · String

   Converts a numeric string into its ordinal form (e.g., “1st”, “2nd”, “23rd”). Requires isDigitsOnly() to be available.

   print('11'.withOrdinal()); // "11th"
   print('23'.withOrdinal()); // "23rd"
   

   withEllipsis(int maxLength) · String

   Show Parameters

   maxLength · int · required

   The maximum number of characters allowed before truncation.

   Truncates the string if its length exceeds maxLength and appends an ellipsis (”…”).

   final long = 'This is a long message';
   print(long.withEllipsis(10)); // "This is a ..."
   

   truncateName() · 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.”).

   final name1 = 'Alice Wonderland';
   print(name1.truncateName()); // "Alice W."
   

   reverse() · String

   Reverses the order of the characters in the string.

   final text = 'dart';
   print(text.reverse()); // "trad"
   

   getLastNCharacters(int n) · String

   Show Parameters

   n · int · required

   The number of characters to retrieve from the end of the string.

   Retrieves the last N characters of the string.

   final id = 'TX202512345';
   print(id.getLastNCharacters(4)); // "2345"