description

# String class abstract final

A sequence of UTF-16 code units.

Strings are mainly used to represent text. A character may be represented by multiple code points, each code point consisting of one or two code units. For example, the Papua New Guinea flag character requires four code units to represent two code points, but should be treated like a single character: "🇵🇬". Platforms that do not support the flag character may show the letters "PG" instead. If the code points are swapped, it instead becomes the Guadeloupe flag "🇬🇵" ("GP").

A string can be either single or multiline. Single line strings are written using matching single or double quotes, and multiline strings are written using triple quotes. The following are all valid Dart strings:

    'Single quotes';
    "Double quotes";
    'Double quotes in "single" quotes';
    "Single quotes in 'double' quotes";

    '''A
    multiline
    string''';

    """
    Another
    multiline
    string""";

Strings are immutable. Although you cannot change a string, you can perform an operation on a string which creates a new string:

    const string = 'Dart is fun';
    print(string.substring(0, 4)); // 'Dart'

You can use the plus (`+`) operator to concatenate strings:

    const string = 'Dart ' + 'is ' + 'fun!';
    print(string); // 'Dart is fun!'

Adjacent string literals are concatenated automatically:

    const string = 'Dart ' 'is ' 'fun!';
    print(string); // 'Dart is fun!'

You can use `${}` to interpolate the value of Dart expressions within strings. The curly braces can be omitted when evaluating identifiers:

    const string = 'dartlang';
    print('$string has ${string.length} letters'); // dartlang has 8 letters

A string is represented by a sequence of Unicode UTF-16 code units accessible through the codeUnitAt or the codeUnits members:

    const string = 'Dart';
    final firstCodeUnit = string.codeUnitAt(0);
    print(firstCodeUnit); // 68, aka U+0044, the code point for 'D'.
    final allCodeUnits = string.codeUnits;
    print(allCodeUnits); // [68, 97, 114, 116]

A string representation of the individual code units is accessible through the index operator:

    const string = 'Dart';
    final charAtIndex = string[0];
    print(charAtIndex); // 'D'

The characters of a string are encoded in UTF-16. Decoding UTF-16, which combines surrogate pairs, yields Unicode code points. Following a similar terminology to Go, Dart uses the name 'rune' for an integer representing a Unicode code point. Use the runes property to get the runes of a string:

    const string = 'Dart';
    final runes = string.runes.toList();
    print(runes); // [68, 97, 114, 116]

For a character outside the Basic Multilingual Plane (plane 0) that is composed of a surrogate pair, runes combines the pair and returns a single integer. For example, the Unicode character for a musical G-clef ('𝄞') with rune value 0x1D11E consists of a UTF-16 surrogate pair: `0xD834` and `0xDD1E`. Using codeUnits returns the surrogate pair, and using `runes` returns their combined value:

    const clef = '\u{1D11E}';
    for (final item in clef.codeUnits) {
      print(item.toRadixString(16));
      // d834
      // dd1e
    }
    for (final item in clef.runes) {
      print(item.toRadixString(16)); // 1d11e
    }

The `String` class cannot be extended or implemented. Attempting to do so yields a compile-time error.

## Other resources

- StringBuffer to efficiently build a string incrementally.
- RegExp to work with regular expressions.
- Strings and regular expressions

Implemented types
  - Comparable<String>
  - Pattern
Available extensions
  - StringToJSString

## Constructors

String.fromCharCode(int charCode)
  Allocates a new string containing the specified `charCode`.
  factory
String.fromCharCodes(Iterable<int> charCodes, [int start = 0, int? end])
  Allocates a new string containing the specified `charCodes`.
  factory
String.fromEnvironment(String name, {String defaultValue = ""})
  Value for `name` in the compilation configuration environment declaration.
  const
  factory

## Properties

codeUnits → List<int>
  An unmodifiable list of the UTF-16 code units of this string.
  no setter
hashCode → int
  A hash code derived from the code units of the string.
  no setter override
isEmpty → bool
  Whether this string is empty.
  no setter
isNotEmpty → bool
  Whether this string is not empty.
  no setter
length → int
  The length of the string.
  no setter
runes → Runes
  An Iterable of Unicode code-points of this string.
  no setter
runtimeType → Type
  A representation of the runtime type of the object.
  no setter inherited
toJS → JSString

  Available on String, provided by the StringToJSString extension

  Converts this String to a JSString.
  no setter

## Methods

allMatches(String string, [int start = 0]) → Iterable<Match>
  Matches this pattern against the string repeatedly.
  inherited
codeUnitAt(int index) → int
  Returns the 16-bit UTF-16 code unit at the given `index`.
compareTo(String other) → int
  Compares this string to `other`.
  override
contains(Pattern other, [int startIndex = 0]) → bool
  Whether this string contains a match of `other`.
endsWith(String other) → bool
  Whether this string ends with `other`.
indexOf(Pattern pattern, [int start = 0]) → int
  Returns the position of the first match of `pattern` in this string, starting at `start`, inclusive:
lastIndexOf(Pattern pattern, [int? start]) → int
  The starting position of the last match `pattern` in this string.
matchAsPrefix(String string, [int start = 0]) → Match?
  Matches this pattern against the start of `string`.
  inherited
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
padLeft(int width, [String padding = ' ']) → String
  Pads this string on the left if it is shorter than `width`.
padRight(int width, [String padding = ' ']) → String
  Pads this string on the right if it is shorter than `width`.
replaceAll(Pattern from, String replace) → String
  Replaces all substrings that match `from` with `replace`.
replaceAllMapped(Pattern from, String replace(Match match)) → String
  Replace all substrings that match `from` by a computed string.
replaceFirst(Pattern from, String to, [int startIndex = 0]) → String
  Creates a new string with the first occurrence of `from` replaced by `to`.
replaceFirstMapped(Pattern from, String replace(Match match), [int startIndex = 0]) → String
  Replace the first occurrence of `from` in this string.
replaceRange(int start, int? end, String replacement) → String
  Replaces the substring from `start` to `end` with `replacement`.
split(Pattern pattern) → List<String>
  Splits the string at matches of `pattern` and returns a list of substrings.
splitMapJoin(Pattern pattern, {String onMatch(Match)?, String onNonMatch(String)?}) → String
  Splits the string, converts its parts, and combines them into a new string.
startsWith(Pattern pattern, [int index = 0]) → bool
  Whether this string starts with a match of `pattern`.
substring(int start, [int? end]) → String
  The substring of this string from `start`, inclusive, to `end`, exclusive.
toLowerCase() → String
  Converts all characters in this string to lower case.
toString() → String
  A string representation of this object.
  inherited
toUpperCase() → String
  Converts all characters in this string to upper case.
trim() → String
  The string without any leading and trailing whitespace.
trimLeft() → String
  The string without any leading whitespace.
trimRight() → String
  The string without any trailing whitespace.

## Operators

operator *(int times) → String
  Creates a new string by concatenating this string with itself a number of times.
operator +(String other) → String
  Creates a new string by concatenating this string with `other`.
operator ==(Object other) → bool
  Whether `other` is a `String` with the same sequence of code units.
  override
operator [](int index) → String
  The character (as a single-code-unit String) at the given `index`.