The dart:core library (API reference) provides a small but critical set of built-in functionality. This library is automatically imported into every Dart program.

The top-levelprint() method takes a single argument (any Object) and displays that object's string value (as returned bytoString()) in the console.

print(anObject);print('I drink$tea.');

For more information on basic strings andtoString(), seeStrings in the language tour.

The dart:core library defines the num, int, and double classes, which have some basic utilities for working with numbers.

You can convert a string into an integer or double with theparse() methods of int and double, respectively:

assert(int.parse('42')==42);assert(int.parse('0x42')==66);assert(double.parse('0.50')==0.5);

Or use the parse() method of num, which creates an integer if possible and otherwise a double:

assert(num.parse('42')isint);assert(num.parse('0x42')isint);assert(num.parse('0.50')isdouble);

To specify the base of an integer, add aradix parameter:

assert(int.parse('42',radix:16)==66);

Use thetoString() method to convert an int or double to a string. To specify the number of digits to the right of the decimal, usetoStringAsFixed(). To specify the number of significant digits in the string, usetoStringAsPrecision():

// Convert an int to a string.assert(42.toString()=='42');​// Convert a double to a string.assert(123.456.toString()=='123.456');​// Specify the number of digits after the decimal.assert(123.456.toStringAsFixed(2)=='123.46');​// Specify the number of significant figures.assert(123.456.toStringAsPrecision(2)=='1.2e+2');assert(double.parse('1.2e+2')==120.0);

For more information, see the API documentation forint,double, andnum. Also see thedart:math section

A string in Dart is an immutable sequence of UTF-16 code units. The language tour has more information aboutstrings. You can use regular expressions (RegExp objects) to search within strings and to replace parts of strings.

The String class defines such methods assplit(),contains(),startsWith(),endsWith(), and more.

You can find particular locations within a string, as well as check whether a string begins with or ends with a particular pattern. For example:

// Check whether a string contains another string.assert('Never odd or even'.contains('odd'));​// Does a string start with another string?assert('Never odd or even'.startsWith('Never'));​// Does a string end with another string?assert('Never odd or even'.endsWith('even'));​// Find the location of a string inside a string.assert('Never odd or even'.indexOf('odd')==6);

You can get the individual characters from a string as Strings or ints, respectively. To be precise, you actually get individual UTF-16 code units; high-numbered characters such as the treble clef symbol ('\u{1D11E}') are two code units apiece.

You can also extract a substring or split a string into a list of substrings:

// Grab a substring.assert('Never odd or even'.substring(6,9)=='odd');​// Split a string using a string pattern.varparts='progressive web apps'.split('');assert(parts.length==3);assert(parts[0]=='progressive');​// Get a UTF-16 code unit (as a string) by index.assert('Never odd or even'[0]=='N');​// Use split() with an empty string parameter to get// a list of all characters (as Strings); good for// iterating.for(finalcharin'hello'.split('')){print(char);}​// Get all the UTF-16 code units in the string.varcodeUnitList='Never odd or even'.codeUnits.toList();assert(codeUnitList[0]==78);

::: In many cases, you want to work with Unicode grapheme clusters as opposed to pure code units. These are characters as they are perceived by the user (for example, "🇬🇧" is one user-perceived character but several UTF-16 code units). For this, the Dart team provides thecharacters package. :::

You can easily convert strings to their uppercase and lowercase variants:

// Convert to uppercase.assert('web apps'.toUpperCase()=='WEB APPS');​// Convert to lowercase.assert('WEB APPS'.toLowerCase()=='web apps');

Remove all leading and trailing white space withtrim(). To check whether a string is empty (length is zero), useisEmpty.

// Trim a string.assert('  hello'.trim()=='hello');​// Check whether a string is empty.assert(''.isEmpty);​// Strings with only white space are not empty.assert(''.isNotEmpty);

Strings are immutable objects, which means you can create them but you can't change them. If you look closely at theString API reference, you'll notice that none of the methods actually changes the state of a String. For example, the methodreplaceAll() returns a new String without changing the original String:

vargreetingTemplate='Hello, NAME!';vargreeting=greetingTemplate.replaceAll(RegExp('NAME'),'Bob');​// greetingTemplate didn't change.assert(greeting!=greetingTemplate);

To programmatically generate a string, you can use StringBuffer. A StringBuffer doesn't generate a new String object untiltoString() is called. ThewriteAll() method has an optional second parameter that lets you specify a separator—in this case, a space.

varsb=StringBuffer();sb..write('Use a StringBuffer for')..writeAll(['efficient','string','creation'],'')..write('.');​varfullString=sb.toString();​assert(fullString=='Use a StringBuffer for efficient string creation.');

The RegExp class provides the same capabilities as JavaScript regular expressions. Use regular expressions for efficient searching and pattern matching of strings.

// Here's a regular expression for one or more digits.vardigitSequence=RegExp(r'\d+');​varlettersOnly='llamas live fifteen to twenty years';varsomeDigits='llamas live 15 to 20 years';​// contains() can use a regular expression.assert(!lettersOnly.contains(digitSequence));assert(someDigits.contains(digitSequence));​// Replace every match with another string.varexedOut=someDigits.replaceAll(digitSequence,'XX');assert(exedOut=='llamas live XX to XX years');

You can work directly with the RegExp class, too. The Match class provides access to a regular expression match.

vardigitSequence=RegExp(r'\d+');varsomeDigits='llamas live 15 to 20 years';​// Check whether the reg exp has a match in a string.assert(digitSequence.hasMatch(someDigits));​// Loop through all matches.for(finalmatchindigitSequence.allMatches(someDigits)){print(match.group(0));// 15, then 20}

Refer to theString API reference for a full list of methods. Also see the API reference forStringBuffer,Pattern,RegExp, andMatch.

Dart ships with a core collections API, which includes classes for lists, sets, and maps.

As the language tour shows, you can use literals to create and initializelists. Alternatively, use one of the List constructors. The List class also defines several methods for adding items to and removing items from lists.

// Create an empty list of strings.vargrains=<String>[];assert(grains.isEmpty);​// Create a list using a list literal.varfruits=['apples','oranges'];​// Add to a list.fruits.add('kiwis');​// Add multiple items to a list.fruits.addAll(['grapes','bananas']);​// Get the list length.assert(fruits.length==5);​// Remove a single item.varappleIndex=fruits.indexOf('apples');fruits.removeAt(appleIndex);assert(fruits.length==4);​// Remove all elements from a list.fruits.clear();assert(fruits.isEmpty);​// You can also create a List using one of the constructors.varvegetables=List.filled(99,'broccoli');assert(vegetables.every((v)=>v=='broccoli'));

UseindexOf() to find the index of an object in a list:

varfruits=['apples','oranges'];​// Access a list item by index.assert(fruits[0]=='apples');​// Find an item in a list.assert(fruits.indexOf('apples')==0);

Sort a list using thesort() method. You can provide a sorting function that compares two objects. This sorting function must return < 0 forsmaller, 0 for thesame, and > 0 forbigger. The following example usescompareTo(), which is defined byComparable and implemented by String.

varfruits=['bananas','apples','oranges'];​// Sort a list.fruits.sort((a,b)=>a.compareTo(b));assert(fruits[0]=='apples');

Lists are parameterized types (generics), so you can specify the type that a list should contain:

// This list should contain only strings.varfruits=<String>[];​fruits.add('apples');varfruit=fruits[0];assert(fruitisString);

fruits.add(5);// Error: 'int' can't be assigned to 'String'

Refer to theList API reference for a full list of methods.

A set in Dart is an unordered collection of unique items. Because a set is unordered, you can't get a set's items by index (position).

// Create an empty set of strings.varingredients=<String>{};​// Add new items to it.ingredients.addAll(['gold','titanium','xenon']);assert(ingredients.length==3);​// Adding a duplicate item has no effect.ingredients.add('gold');assert(ingredients.length==3);​// Remove an item from a set.ingredients.remove('gold');assert(ingredients.length==2);​// You can also create sets using// one of the constructors.varatomicNumbers=Set.from([79,22,54]);

Usecontains() andcontainsAll() to check whether one or more objects are in a set:

varingredients=Set<String>();ingredients.addAll(['gold','titanium','xenon']);​// Check whether an item is in the set.assert(ingredients.contains('titanium'));​// Check whether all the items are in the set.assert(ingredients.containsAll(['titanium','xenon']));

An intersection is a set whose items are in two other sets.

varingredients=Set<String>();ingredients.addAll(['gold','titanium','xenon']);​// Create the intersection of two sets.varnobleGases=Set.from(['xenon','argon']);varintersection=ingredients.intersection(nobleGases);assert(intersection.length==1);assert(intersection.contains('xenon'));

Refer to theSet API reference for a full list of methods.

A map, commonly known as adictionary orhash, is an unordered collection of key-value pairs. Maps associate a key to some value for easy retrieval. Unlike in JavaScript, Dart objects are not maps.

You can declare a map using a terse literal syntax, or you can use a traditional constructor:

// Maps often use strings as keys.varhawaiianBeaches={'Oahu':['Waikiki','Kailua','Waimanalo'],'Big Island':['Wailea Bay','Pololu Beach'],'Kauai':['Hanalei','Poipu'],};​// Maps can be built from a constructor.varsearchTerms=Map();​// Maps are parameterized types; you can specify what// types the key and value should be.varnobleGases=Map<int,String>();

You add, get, and set map items using the bracket syntax. Useremove() to remove a key and its value from a map.

varnobleGases={54:'xenon'};​// Retrieve a value with a key.assert(nobleGases[54]=='xenon');​// Check whether a map contains a key.assert(nobleGases.containsKey(54));​// Remove a key and its value.nobleGases.remove(54);assert(!nobleGases.containsKey(54));

You can retrieve all the values or all the keys from a map:

varhawaiianBeaches={'Oahu':['Waikiki','Kailua','Waimanalo'],'Big Island':['Wailea Bay','Pololu Beach'],'Kauai':['Hanalei','Poipu'],};​// Get all the keys as an unordered collection// (an Iterable).varkeys=hawaiianBeaches.keys;​assert(keys.length==3);assert(Set.from(keys).contains('Oahu'));​// Get all the values as an unordered collection// (an Iterable of Lists).varvalues=hawaiianBeaches.values;assert(values.length==3);assert(values.any((v)=>v.contains('Waikiki')));

To check whether a map contains a key, usecontainsKey(). Because map values can be null, you cannot rely on simply getting the value for the key and checking for null to determine the existence of a key.

varhawaiianBeaches={'Oahu':['Waikiki','Kailua','Waimanalo'],'Big Island':['Wailea Bay','Pololu Beach'],'Kauai':['Hanalei','Poipu'],};​assert(hawaiianBeaches.containsKey('Oahu'));assert(!hawaiianBeaches.containsKey('Florida'));

Use theputIfAbsent() method when you want to assign a value to a key if and only if the key does not already exist in a map. You must provide a function that returns the value.

varteamAssignments=<String,String>{};teamAssignments.putIfAbsent('Catcher',()=>pickToughestKid());assert(teamAssignments['Catcher']!=null);

Refer to theMap API reference for a full list of methods.

List, Set, and Map share common functionality found in many collections. Some of this common functionality is defined by the Iterable class, which List and Set implement.

varcoffees=<String>[];varteas=['green','black','chamomile','earl grey'];assert(coffees.isEmpty);assert(teas.isNotEmpty);

varteas=['green','black','chamomile','earl grey'];​teas.forEach((tea)=>print('I drink$tea'));

hawaiianBeaches.forEach((k,v){print('I want to visit$k and swim at$v');// I want to visit Oahu and swim at// [Waikiki, Kailua, Waimanalo], etc.});

varteas=['green','black','chamomile','earl grey'];​varloudTeas=teas.map((tea)=>tea.toUpperCase());loudTeas.forEach(print);

varloudTeas=teas.map((tea)=>tea.toUpperCase()).toList();

varteas=['green','black','chamomile','earl grey'];​// Chamomile is not caffeinated.boolisDecaffeinated(StringteaName)=>teaName=='chamomile';​// Use where() to find only the items that return true// from the provided function.vardecaffeinatedTeas=teas.where((tea)=>isDecaffeinated(tea));// or teas.where(isDecaffeinated)​// Use any() to check whether at least one item in the// collection satisfies a condition.assert(teas.any(isDecaffeinated));​// Use every() to check whether all the items in a// collection satisfy a condition.assert(!teas.every(isDecaffeinated));

For a full list of methods, refer to theIterable API reference, as well as those forList,Set, andMap.

TheUri class provides functions to encode and decode strings for use in URIs (which you might know asURLs). These functions handle characters that are special for URIs, such as& and=. The Uri class also parses and exposes the components of a URI—host, port, scheme, and so on.

To encode and decode charactersexcept those with special meaning in a URI (such as/,:,&,#), use theencodeFull() anddecodeFull() methods. These methods are good for encoding or decoding a fully qualified URI, leaving intact special URI characters.

varuri='https://example.org/api?foo=some message';​varencoded=Uri.encodeFull(uri);assert(encoded=='https://example.org/api?foo=some%20message');​vardecoded=Uri.decodeFull(encoded);assert(uri==decoded);

Notice how only the space betweensome andmessage was encoded.

To encode and decode all of a string's characters that have special meaning in a URI, including (but not limited to)/,&, and:, use theencodeComponent() anddecodeComponent() methods.

varuri='https://example.org/api?foo=some message';​varencoded=Uri.encodeComponent(uri);assert(encoded=='https%3A%2F%2Fexample.org%2Fapi%3Ffoo%3Dsome%20message',);​vardecoded=Uri.decodeComponent(encoded);assert(uri==decoded);

Notice how every special character is encoded. For example,/ is encoded to%2F.

If you have a Uri object or a URI string, you can get its parts using Uri fields such aspath. To create a Uri from a string, use theparse() static method:

varuri=Uri.parse('https://example.org:8080/foo/bar#frag');​assert(uri.scheme=='https');assert(uri.host=='example.org');assert(uri.path=='/foo/bar');assert(uri.fragment=='frag');assert(uri.origin=='https://example.org:8080');

See theUri API reference for more URI components that you can get.

You can build up a URI from individual parts using theUri() constructor:

varuri=Uri(scheme:'https',host:'example.org',path:'/foo/bar',fragment:'frag',queryParameters:{'lang':'dart'},);assert(uri.toString()=='https://example.org/foo/bar?lang=dart#frag');

If you don't need to specify a fragment, to create a URI with a http or https scheme, you can instead use theUri.http orUri.https factory constructors:

varhttpUri=Uri.http('example.org','/foo/bar',{'lang':'dart'});varhttpsUri=Uri.https('example.org','/foo/bar',{'lang':'dart'});​assert(httpUri.toString()=='http://example.org/foo/bar?lang=dart');assert(httpsUri.toString()=='https://example.org/foo/bar?lang=dart');

A DateTime object is a point in time. The time zone is either UTC or the local time zone.

You can create DateTime objects using several constructors and methods:

// Get the current date and time.varnow=DateTime.now();​// Create a new DateTime with the local time zone.vary2k=DateTime(2000);// January 1, 2000​// Specify the month and day.y2k=DateTime(2000,1,2);// January 2, 2000​// Specify the date as a UTC time.y2k=DateTime.utc(2000);// 1/1/2000, UTC​// Specify a date and time in ms since the Unix epoch.y2k=DateTime.fromMillisecondsSinceEpoch(946684800000,isUtc:true);​// Parse an ISO 8601 date in the UTC time zone.y2k=DateTime.parse('2000-01-01T00:00:00Z');​// Create a new DateTime from an existing one, adjusting just some properties:varsameTimeLastYear=now.copyWith(year:now.year-1);

// 1/1/2000, UTCvary2k=DateTime.utc(2000);assert(y2k.millisecondsSinceEpoch==946684800000);​// 1/1/1970, UTCvarunixEpoch=DateTime.utc(1970);assert(unixEpoch.millisecondsSinceEpoch==0);

vary2k=DateTime.utc(2000);​// Add one year.vary2001=y2k.add(constDuration(days:366));assert(y2001.year==2001);​// Subtract 30 days.vardecember2000=y2001.subtract(constDuration(days:30));assert(december2000.year==2000);assert(december2000.month==12);​// Calculate the difference between two dates.// Returns a Duration object.varduration=y2001.difference(y2k);assert(duration.inDays==366);// y2k was a leap year.

For a full list of methods, refer to the API reference forDateTime andDuration.

The core library contains various utility classes, useful for sorting, mapping values, and iterating.

Implement theComparable interface to indicate that an object can be compared to another object, usually for sorting. ThecompareTo() method returns < 0 forsmaller, 0 for thesame, and > 0 forbigger.

classLineimplementsComparable<Line>{finalintlength;constLine(this.length);​@overrideintcompareTo(Lineother)=>length-other.length;}​voidmain(){varshort=constLine(1);varlong=constLine(100);assert(short.compareTo(long)<0);}

Each object in Dart automatically provides an integer hash code, and thus can be used as a key in a map. However, you can override thehashCode getter to generate a custom hash code. If you do, you might also want to override the== operator. Objects that are equal (via==) must have identical hash codes. A hash code doesn't have to be unique, but it should be well distributed.

classPerson{finalStringfirstName,lastName;​Person(this.firstName,this.lastName);​// Override hashCode using the static hashing methods// provided by the `Object` class.@overrideintgethashCode=>Object.hash(firstName,lastName);​// You should generally implement operator `==` if you// override `hashCode`.@overridebooloperator==(Objectother){returnotherisPerson&&other.firstName==firstName&&other.lastName==lastName;}}​voidmain(){varp1=Person('Bob','Smith');varp2=Person('Bob','Smith');varp3='not a person';assert(p1.hashCode==p2.hashCode);assert(p1==p2);assert(p1!=p3);}

TheIterable andIterator classes support sequential access to a collection of values. To practice using these collections, follow theIterable collections tutorial.

If you create a class that can provide Iterators for use in for-in loops, extend (if possible) or implement Iterable. Implement Iterator to define the actual iteration ability.

classProcess{// Represents a process...}​classProcessIteratorimplementsIterator<Process>{@overrideProcessgetcurrent=>...@overrideboolmoveNext()=>...}​// A mythical class that lets you iterate through all// processes. Extends a subclass of [Iterable].classProcessesextendsIterableBase<Process>{@overridefinalIterator<Process>iterator=ProcessIterator();}​voidmain(){// Iterable objects can be used with for-in.for(finalprocessinProcesses()){// Do something with the process.}}

The Dart core library defines many common exceptions and errors. Exceptions are considered conditions that you can plan ahead for and catch. Errors are conditions that you don't expect or plan for.

A couple of the most common errors are:

NoSuchMethodError

Thrown when a receiving object (which might benull) does not implement a method.

ArgumentError

Can be thrown by a method that encounters an unexpected argument.

Throwing an application-specific exception is a common way to indicate that an error has occurred. You can define a custom exception by implementing the Exception interface:

classFooExceptionimplementsException{finalString?msg;​constFooException([this.msg]);​@overrideStringtoString()=>msg??'FooException';}

For more information, seeExceptions (in the language tour) and theException API reference.

Dart is agarbage-collected language, which means that any Dart object that isn't referenced can be disposed by the garbage collector. This default behavior might not be desirable in some scenarios involving native resources or if the target object can't be modified.

AWeakReference stores a reference to the target object that does not affect how it is collected by the garbage collector. Another option is to use anExpando to add properties to an object.

AFinalizer can be used to execute a callback function after an object is no longer referenced. However, it is not guaranteed to execute this callback.

ANativeFinalizer provides stronger guarantees for interacting with native code usingdart:ffi; its callback is invoked at least once after the object is no longer referenced. Also, it can be used to close native resources such as a database connection or open files.

To ensure that an object won't be garbage collected and finalized too early, classes can implement theFinalizable interface. When a local variable is Finalizable, it won't be garbage collected until the code block where it is declared has exited.