dart:core

String class

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:

var string = 'Dart is fun';
var newString = string.substring(0, 5);

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

'Dart ' + 'is ' + 'fun!'; // 'Dart is fun!'

Adjacent string literals are concatenated automatically:

'Dart ' 'is ' 'fun!';    // 'Dart is fun!'

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

string = 'dartlang';
'$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:

string = 'Dart';
string.codeUnitAt(0); // 68
string.codeUnits;     // [68, 97, 114, 116]

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

string[0];            // '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, we use the name 'rune' for an integer representing a Unicode code point. Use the runes property to get the runes of a string:

string.runes.toList(); // [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:

var clef = '\u{1D11E}';
clef.codeUnits;         // [0xD834, 0xDD1E]
clef.runes.toList();    // [0x1D11E]

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

Other resources

See StringBuffer to efficiently build a string incrementally. See RegExp to work with regular expressions.

Also see:

• Strings and regular expressions

Implemented types

• Comparable<String>
• Pattern

Constructors

String.fromCharCode(int charCode)

factory

Allocates a new string containing the specified charCode. [...]

String.fromCharCodes(Iterable<int> charCodes, [int start = 0, int? end])

factory

Allocates a new string containing the specified charCodes. [...]

String.fromEnvironment(String name, {String defaultValue = ""})

const

factory

The string value of the environment declaration name. [...]

Properties

codeUnits → List<int>

read-only

An unmodifiable list of the UTF-16 code units of this string.

hashCode → int

read-only, override

A hash code derived from the code units of the string. [...]

isEmpty → bool

read-only

Whether this string is empty.

isNotEmpty → bool

read-only

Whether this string is not empty.

length → int

read-only

The length of the string. [...]

runes → Runes

read-only

An Iterable of Unicode code-points of this string. [...]

runtimeType → Type

read-only, inherited

A representation of the runtime type of the object.

Methods

allMatches(String string, [int start = 0]) → Iterable<Match>

inherited

Matches this pattern against the string repeatedly. [...]

codeUnitAt(int index) → int

Returns the 16-bit UTF-16 code unit at the given index.

compareTo(String other) → int

override

Compares this string to other. [...]

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?

inherited

Matches this pattern against the start of string. [...]

noSuchMethod(Invocation invocation) → dynamic

inherited

Invoked when a non-existent method or property is accessed. [...]

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

inherited

A string representation of this object. [...]

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

override

Whether other is a String with the same sequence of code units. [...]

operator [](int index) → String

The character (as a single-code-unit String) at the given index. [...]