dart:core

A biblioteca dart:core (referência da API) oferece um conjunto pequeno, mas fundamental, de funcionalidades integradas. Essa biblioteca é importada automaticamente em todo programa Dart.

O método de nível superior print() recebe um único argumento (qualquer Object) e exibe no console o valor da string desse objeto (conforme retornado por toString()).

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

Para mais informações sobre strings básicas e toString(), veja Strings no tour da linguagem.

A biblioteca dart:core define as classes num, int e double, que têm alguns utilitários básicos para trabalhar com números.

Você pode converter uma string em um inteiro ou em um double com os métodos parse() de int e double, respectivamente:

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

Ou use o método parse() de num, que cria um inteiro quando possível e, caso contrário, um double:

assert(num.parse('42') is int);
assert(num.parse('0x42') is int);
assert(num.parse('0.50') is double);

Para especificar a base de um inteiro, adicione um parâmetro radix:

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

Use o método toString() para converter um int ou double em string. Para especificar o número de dígitos à direita da vírgula decimal, use toStringAsFixed(). Para especificar o número de algarismos significativos na string, use toStringAsPrecision():

// 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);

Para mais informações, veja a documentação da API de int, double, e num. Veja também a seção dart:math

Uma string em Dart é uma sequência imutável de unidades de código UTF-16. O tour da linguagem tem mais informações sobre strings. Você pode usar expressões regulares (objetos RegExp) para pesquisar dentro de strings e para substituir partes de strings.

A classe String define métodos como split(), contains(), startsWith(), endsWith() e outros.

Você pode encontrar posições específicas dentro de uma string, além de verificar se ela começa ou termina com um determinado padrão. Por exemplo:

// 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);

Você pode obter os caracteres individuais de uma string como Strings ou ints, respectivamente. Para ser preciso, você obtém unidades de código UTF-16 individuais; caracteres de numeração alta, como o símbolo de clave de sol ('\u{1D11E}'), ocupam duas unidades de código cada.

Você também pode extrair uma substring ou dividir uma string em uma lista de substrings:

// Grab a substring.
assert('Never odd or even'.substring(6, 9) == 'odd');
​
// Split a string using a string pattern.
var parts = '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 (final char in 'hello'.split('')) {
  print(char);
}
​
// Get all the UTF-16 code units in the string.
var codeUnitList = 'Never odd or even'.codeUnits.toList();
assert(codeUnitList[0] == 78);

Você pode converter facilmente strings para suas versões em maiúsculas e minúsculas:

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

Remova todos os espaços em branco no início e no fim com trim(). Para verificar se uma string está vazia (tamanho zero), use isEmpty.

// 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 são objetos imutáveis, o que significa que você pode criá-las, mas não pode alterá-las. Se você observar com atenção a referência da API de String, vai notar que nenhum dos métodos realmente altera o estado de uma String. Por exemplo, o método replaceAll() retorna uma nova String sem alterar a String original:

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

Para gerar uma string programaticamente, você pode usar StringBuffer. Um StringBuffer não gera um novo objeto String até que toString() seja chamado. O método writeAll() tem um segundo parâmetro opcional que permite especificar um separador—neste caso, um espaço.

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

A classe RegExp oferece as mesmas capacidades das expressões regulares do JavaScript. Use expressões regulares para pesquisa eficiente e correspondência de padrões em strings.

// Here's a regular expression for one or more digits.
var digitSequence = RegExp(r'\d+');
​
var lettersOnly = 'llamas live fifteen to twenty years';
var someDigits = '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.
var exedOut = someDigits.replaceAll(digitSequence, 'XX');
assert(exedOut == 'llamas live XX to XX years');

Você também pode trabalhar diretamente com a classe RegExp. A classe Match dá acesso a uma correspondência de expressão regular.

var digitSequence = RegExp(r'\d+');
var someDigits = '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 (final match in digitSequence.allMatches(someDigits)) {
  print(match.group(0)); // 15, then 20
}

Consulte a referência da API de String para ver a lista completa de métodos. Veja também a referência da API de StringBuffer, Pattern, RegExp, e Match.

O Dart traz uma API de coleções no core, que inclui classes para listas, conjuntos e mapas.

Como o tour da linguagem mostra, você pode usar literais para criar e inicializar listas. Alternativamente, use um dos construtores de List. A classe List também define vários métodos para adicionar itens e remover itens de listas.

// Create an empty list of strings.
var grains = <String>[];
assert(grains.isEmpty);
​
// Create a list using a list literal.
var fruits = ['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.
var appleIndex = 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.
var vegetables = List.filled(99, 'broccoli');
assert(vegetables.every((v) => v == 'broccoli'));

Use indexOf() para encontrar o índice de um objeto em uma lista:

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

Ordene uma lista usando o método sort(). Você pode fornecer uma função de ordenação que compara dois objetos. Essa função deve retornar < 0 para menor, 0 para igual e > 0 para maior. O exemplo a seguir usa compareTo(), que é definido pela Comparable e implementado por String.

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

Listas são tipos parametrizados (generics), então você pode especificar o tipo que uma lista deve conter:

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

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

Consulte a referência da API de List para ver a lista completa de métodos.

Um conjunto (set) em Dart é uma coleção não ordenada de itens únicos. Como um conjunto não é ordenado, você não pode obter os itens de um conjunto por índice (posição).

// Create an empty set of strings.
var ingredients = <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.
var atomicNumbers = Set.from([79, 22, 54]);

Use contains() e containsAll() para verificar se um ou mais objetos estão em um conjunto:

var ingredients = 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']));

Uma interseção é um conjunto cujos itens estão em outros dois conjuntos.

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

Consulte a referência da API de Set para ver a lista completa de métodos.

Um mapa, conhecido comumente como dicionário ou hash, é uma coleção não ordenada de pares chave-valor. Mapas associam uma chave a algum valor para facilitar a recuperação. Diferentemente do JavaScript, objetos Dart não são mapas.

Você pode declarar um mapa usando uma sintaxe de literal concisa, ou pode usar um construtor tradicional:

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

Você adiciona, obtém e define itens de mapa usando a sintaxe de colchetes. Use remove() para remover uma chave e seu valor de um mapa.

var nobleGases = {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));

Você pode obter todos os valores ou todas as chaves de um mapa:

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

Para verificar se um mapa contém uma chave, use containsKey(). Como os valores de mapas podem ser null, você não pode confiar apenas em obter o valor da chave e verificar null para determinar se a chave existe.

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

Use o método putIfAbsent() quando quiser atribuir um valor a uma chave somente se a chave ainda não existir em um mapa. Você precisa fornecer uma função que retorne o valor.

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

Consulte a referência da API de Map para ver a lista completa de métodos.

List, Set e Map compartilham funcionalidades comuns encontradas em muitas coleções. Parte dessa funcionalidade comum é definida pela classe Iterable, que List e Set implementam.

Use isEmpty ou isNotEmpty para verificar se uma lista, um conjunto ou um mapa tem itens:

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

Para aplicar uma função a cada item de uma lista, conjunto ou mapa, você pode usar forEach():

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

Ao invocar forEach() em um mapa, sua função precisa receber dois argumentos (a chave e o valor):

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.
});

Iterables oferecem o método map(), que entrega todos os resultados em um único objeto:

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

Para forçar que sua função seja chamada imediatamente em cada item, use map().toList() ou map().toSet():

var loudTeas = teas.map((tea) => tea.toUpperCase()).toList();

Use o método where() de Iterable para obter todos os itens que correspondem a uma condição. Use os métodos any() e every() de Iterable para verificar se alguns ou todos os itens correspondem a uma condição.

var teas = ['green', 'black', 'chamomile', 'earl grey'];
​
// Chamomile is not caffeinated.
bool isDecaffeinated(String teaName) => teaName == 'chamomile';
​
// Use where() to find only the items that return true
// from the provided function.
var decaffeinatedTeas = 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));

Para a lista completa de métodos, consulte a referência da API de Iterable, bem como as de List, Set, e Map.

A classe Uri oferece funções para codificar e decodificar strings para uso em URIs (que você pode conhecer como URLs). Essas funções tratam caracteres que são especiais para URIs, como & e =. A classe Uri também analisa e expõe os componentes de uma URI—host, porta, esquema e assim por diante.

Para codificar e decodificar caracteres exceto aqueles com significado especial em uma URI (como /, :, &, #), use os métodos encodeFull() e decodeFull(). Esses métodos são bons para codificar ou decodificar uma URI completa, mantendo intactos os caracteres especiais de URI.

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

Observe como apenas o espaço entre some e message foi codificado.

Para codificar e decodificar todos os caracteres de uma string que têm significado especial em uma URI, incluindo (mas não se limitando a) /, & e :, use os métodos encodeComponent() e decodeComponent().

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

Observe como cada caractere especial foi codificado. Por exemplo, / é codificado como %2F.

Se você tem um objeto Uri ou uma string de URI, pode obter suas partes usando campos do Uri como path. Para criar um Uri a partir de uma string, use o método estático parse():

var uri = 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');

Veja a referência da API de Uri para mais componentes de URI que você pode obter.

Você pode montar uma URI a partir de partes individuais usando o construtor Uri():

var uri = 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');

Se você não precisa especificar um fragmento, para criar uma URI com esquema http ou https, pode usar os construtores de fábrica Uri.http ou Uri.https:

var httpUri = Uri.http('example.org', '/foo/bar', {'lang': 'dart'});
var httpsUri = 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');

Um objeto DateTime é um ponto no tempo. O fuso horário é UTC ou o fuso horário local.

Você pode criar objetos DateTime usando vários construtores e métodos:

// Get the current date and time.
var now = DateTime.now();
​
// Create a new DateTime with the local time zone.
var y2k = 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:
var sameTimeLastYear = now.copyWith(year: now.year - 1);

A propriedade millisecondsSinceEpoch de uma data retorna o número de milissegundos desde a "Unix epoch"—1º de janeiro de 1970, UTC:

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

Use a classe Duration para calcular a diferença entre duas datas e para avançar ou recuar uma data:

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

Para a lista completa de métodos, consulte a referência da API de DateTime e Duration.

A biblioteca core contém várias classes utilitárias, úteis para ordenar, mapear valores e iterar.

Implemente a interface Comparable para indicar que um objeto pode ser comparado com outro objeto, normalmente para ordenação. O método compareTo() retorna < 0 para menor, 0 para igual e > 0 para maior.

class Line implements Comparable<Line> {
  final int length;
  const Line(this.length);
​
  @override
  int compareTo(Line other) => length - other.length;
}
​
void main() {
  var short = const Line(1);
  var long = const Line(100);
  assert(short.compareTo(long) < 0);
}

Cada objeto em Dart fornece automaticamente um código hash inteiro e, por isso, pode ser usado como chave em um mapa. No entanto, você pode sobrescrever o getter hashCode para gerar um código hash personalizado. Se fizer isso, você também pode querer sobrescrever o operador ==. Objetos que são iguais (via ==) precisam ter códigos hash idênticos. Um código hash não precisa ser único, mas deve ser bem distribuído.

class Person {
  final String firstName, lastName;
​
  Person(this.firstName, this.lastName);
​
  // Override hashCode using the static hashing methods
  // provided by the `Object` class.
  @override
  int get hashCode => Object.hash(firstName, lastName);
​
  // You should generally implement operator `==` if you
  // override `hashCode`.
  @override
  bool operator ==(Object other) {
    return other is Person &&
        other.firstName == firstName &&
        other.lastName == lastName;
  }
}
​
void main() {
  var p1 = Person('Bob', 'Smith');
  var p2 = Person('Bob', 'Smith');
  var p3 = 'not a person';
  assert(p1.hashCode == p2.hashCode);
  assert(p1 == p2);
  assert(p1 != p3);
}

As classes Iterable e Iterator oferecem acesso sequencial a uma coleção de valores. Para praticar o uso dessas coleções, siga o tutorial de coleções Iterable.

Se você criar uma classe que possa fornecer Iterators para uso em loops for-in, estenda (se possível) ou implemente Iterable. Implemente Iterator para definir a capacidade de iteração em si.

class Process {
  // Represents a process...
}
​
class ProcessIterator implements Iterator<Process> {
  @override
  Process get current => ...
  @override
  bool moveNext() => ...
}
​
// A mythical class that lets you iterate through all
// processes. Extends a subclass of [Iterable].
class Processes extends IterableBase<Process> {
  @override
  final Iterator<Process> iterator = ProcessIterator();
}
​
void main() {
  // Iterable objects can be used with for-in.
  for (final process in Processes()) {
    // Do something with the process.
  }
}

A biblioteca core do Dart define muitas exceções e erros comuns. Exceções são condições que você pode prever e capturar. Erros são condições que você não espera nem planeja.

Dois dos erros mais comuns são:

NoSuchMethodError

Lançado quando um objeto receptor (que pode ser null) não implementa um método.

ArgumentError

Pode ser lançado por um método que encontra um argumento inesperado.

Lançar uma exceção específica da aplicação é uma forma comum de indicar que ocorreu um erro. Você pode definir uma exceção personalizada implementando a interface Exception:

class FooException implements Exception {
  final String? msg;
​
  const FooException([this.msg]);
​
  @override
  String toString() => msg ?? 'FooException';
}

Para mais informações, veja Exceções (no tour da linguagem) e a referência da API de Exception.

Dart é uma linguagem com coleta de lixo, o que significa que qualquer objeto Dart que não seja referenciado pode ser descartado pelo coletor de lixo. Esse comportamento padrão pode não ser desejável em alguns cenários envolvendo recursos nativos ou quando o objeto alvo não pode ser modificado.

Um WeakReference armazena uma referência ao objeto alvo sem afetar a forma como ele é coletado pelo coletor de lixo. Outra opção é usar um Expando para adicionar propriedades a um objeto.

Um Finalizer pode ser usado para executar uma função de callback depois que um objeto não é mais referenciado. No entanto, não há garantia de que esse callback será executado.

Um NativeFinalizer oferece garantias mais fortes para interagir com código nativo usando dart:ffi; seu callback é invocado pelo menos uma vez depois que o objeto não é mais referenciado. Além disso, ele pode ser usado para fechar recursos nativos como uma conexão com banco de dados ou arquivos abertos.

Para garantir que um objeto não será coletado e finalizado cedo demais, classes podem implementar a interface Finalizable. Quando uma variável local é Finalizable, ela não será coletada pelo coletor de lixo até que o bloco de código em que foi declarada seja encerrado.