Safe

The Strings package provides null safe wrappers for each of the String methods.

Generally, the Safe methods convert a null String? to an empty String before passing the string to the wrapped String method.

In some cases we do additional processing to avoid RangeExceptions and other problems caused by an empty String. These exceptions are noted below.

length

Refer to String.length

Strings.length('abc');
-> 3
Strings.length(null);
-> 0

codeUnits

Refer to String.codeUnits

Strings.codeUnits('abc')
-> [0xxx, 0xyy, 0xzz]
Strings.codeUnits(null)
-> []

runes

Refer to String.runes

Strings.runes('abc')
-> list of runes
Strings.runes(null)
-> []

compareTo

  static int compareTo(String? string, String? other,
      {bool nullIsLessThan = true})

The compareTo method returns two Strings returning 1, 0 or -1.

If both string and other are null then -1 is returned.

If one of string and other are null then -1 or ` is returned based on 'nullIsLessThan'.

If nullIsLessThan is true than null is treated as less than all other strings.

If nullIsLessThan is false then null is treated as greater than all other strings.

contains

Refer to String.contains

Strings.contains('abc', 'ab')
-> true
Strings.contains(null, 'ab')
-> false

endsWith

Refer to String.endsWith

Strings.endsWith('abc', 'bc')
-> true
Strings.endsWith(null, 'ab')
-> false

indexOf

Refer to String.indexOf

Strings.indexOf('abcdef', 'abc);
-> 3
Strings.indexOf(null, 'abc);
-> -1

lastIndexOf

Refer to String.lastIndexOf

Strings.lastIndexOf('abcdefabc', 'abc); 
-> 6 
Strings.lastIndexOf(null, 'abc); 
-> -1

matchAsPrefix

Strings.matchAsPrefix(null, 'abc')
-> null

padLeft

Refer to String.padLeft

Strings.padLeft('123', 4, '0');
-> 0123
Strings.padLeft(null, 4, '0');
-> 0000

padRight

Refer to String.padRight

Strings.padRight('123', 4, '0');
-> 1230
Strings.padRight(null, 4, '0');
-> 0000

replaceAll

Refer to String.replaceAll

Strings.replaceAll('abc', 'ab', 'A');
-> 'Ac'
Strings.replaceAll(null, 'ab', 'A');
-> ''

replaceAllMapped

Refer to String.replaceAllMapped

Strings.replaceAllMapped('abc', 'a', (match) -> 'b');
-> 'bbc';
Strings.replaceAllMapped(null, 'a', (match) -> 'b');
-> ''

replaceFirst

Refer to String.replaceFirst

Strings.replaceFirst('abcabc', 'abc', 'def);
-> 'defabc'
Strings.replaceFirst(null, 'abc', 'def);
-> ''

replaceFirstMapped

Refer to String.replaceFirstMapped

Strings.replaceFirstMapped('abcabc', 'a', (match) -> 'b');
-> 'bbcabc';
Strings.replaceFirstMapped(null, 'a', (match) -> 'b');
-> ''

replaceRange

Refer to String.replaceRange

Strings.replaceRange('abcdef', 3, 6, 'abc');
-> 'abcabc'
Strings.replaceRange(null, 3, 6, 'abc');
-> ''

split

Refer to String.split

Strings.split('a,b,c,d', ',');
-> ['a', 'b', 'c', 'd'];
Strings.split(null, ',');
-> [];

splitMapJoin

Refer to String.splitMapJoin

Strings.splitMapJoin('Eats sleeps leaves', RegExp(r'sleeps'),
     onMatch: (m) => '${m[0]}',
    onNonMatch: (n) => '*');
 -> '*sleeps*'
 Strings.splitMapJoin(null, RegExp(r'sleeps'),
     onMatch: (m) => '${m[0]}',
    onNonMatch: (n) => '*');
-> ''

startsWith

Refer to String.startsWith

Strings.startsWith('abcdef', 'abc');
-> true
Strings.startsWith(null, 'abc');
-> false

substring

Refer to String.substring

The Strings version of substring has special handling of a null string argument.

Instead of replacing it with an empty string we return a string containing spaces of the length required to fulfill the requested start/end index. If end is not passed then we return a single space.

Strings.substring('abcdef', 0, 3);
-> 'abc'
Strings.substring(null, 0, 3);
'   '

toLowerCase

Refer to String.toLowerCase

Strings.toLowerCase('ABC');
-> 'abc'
Strings.toLowerCase(null);
-> '';

toUpperCase

Refer to String.toUpperCase

Strings.toUpperCase('abc');
-> ABC
Strings.toUpperCase(null);
-> ''

trim

Refer to String.trim

Strings.trim('  abc  ');
-> 'abc';
Strings.trim(null);
-> ''

trimLeft

Refer to String.trimLeft

Strings.trimLeft('  abc ');
-> 'abc '
Strings.trimLeft(null);
-> ''

trimRight

Refer to String.trimRight

Strings.trimRight('  abc ');
-> '  abc'
Strings.trimRight(null);
-> ''