Records in Dart: several values without a class

A function that finds the coldest and the hottest of five readings has two answers, 27 and 35, but a return statement hands back one value. Before Dart 3 that meant a List that forgets which number is which, a Map whose keys nobody checks, or a class written only to carry two ints. A record carries both in one value, with a type the compiler checks and an == that compares contents.

You will build records with positional and named fields and read them through their getters, see which names belong to a record’s type, measure when two records are equal and use them as keys of a seat map, return two values from one function, and decide when a class or a map fits better than a record.

A record holds a fixed set of fields, read through getters

ticket.dart builds one value for a train ticket: the train number and the two stations, plus the coach and the seat by name:

void main() {
  // Three positional fields and two named ones, written in any order.
  final ticket = ('12127', coach: 'B2', 'Pune', seat: 41, 'Mumbai');
  print(ticket);
  print('train ${ticket.$1}, from ${ticket.$2} to ${ticket.$3}');
  print('coach ${ticket.coach}, seat ${ticket.seat}');
}

(12127, Pune, Mumbai, coach: B2, seat: 41)
train 12127, from Pune to Mumbai
coach B2, seat 41

All five values went into one object, written as a comma-separated list in parentheses. That object is a recordrecord: An anonymous, immutable value that bundles a fixed set of positional and named fields, each with its own type. Records need no declaration and compare equal when their shape and fields are equal.; the records page calls records an “anonymous, immutable, aggregate type”, since a record needs no declaration, cannot change, and bundles several values. The values written on their own are positional fieldspositional field: A field of a record written without a name and read by its position, as $1, $2 and so on, counting only the positional fields from the left., and the ones written as a name, a colon and a value are named fieldsnamed field: A field of a record written as name: value and read through a getter of the same name. Its name is part of the record's type, and the order of named fields is not.. The two kinds may be mixed in any order. Step through how each field is read:

Positional fields are read as $1, $2 and $3, numbered among the positional fields only, so ‘Pune’ is $2 even though coach stands between it and the train number. Named fields are read by their names. The printed form put the positional fields first; the specification leaves the order of named fields in that text open and lets optimised builds print records in other ways, so use it for debugging, never as output a user reads.

Every field has a getter and none has a setter. no_setter.dart tries to move a passenger to row C:

void main() {
  final seat = (row: 'B', number: 12);
  seat.row = 'C';
  print(seat);
}

no_setter.dart:3:8: Error: The setter 'row' isn't defined for the type '({int number, String row})'.
Try correcting the name to the name of an existing setter, or defining a setter or field named 'row'.
  seat.row = 'C';
       ^^^

The compiler stopped with “The setter ‘row’ isn’t defined” and the program never ran, with exit status 254. The type in the message lists number before row: named fields are kept sorted by name, because the order you write them in is not part of the type. To change a field, build a new record with the new value.

Parentheses alone do not make a record. one_field.dart wraps 42 twice, once with a comma:

void main() {
  final a = (42);
  final b = (42,);
  print('(42) is ${a.runtimeType}, (42,) is ${b.runtimeType}');
  print('b.\$1 = ${b.$1}');
  final nothing = ();
  print('() is ${nothing.runtimeType}');
}

(42) is int, (42,) is (int)
b.$1 = 42
() is ()

(42) is the number 42 in parentheses, an int. (42,) is a record with one positional field, whose type prints as (int) and whose $1 is 42. The trailing comma is needed only for a single positional field: (city: 'Pune') is a record without one, because the name already marks it, and () is the empty record.

A record’s type is its shape, and named fields belong to it

Record types are written the way a function’s parameters are: (int, String) for two positional fields, and ({double lat, double lng}) for named fields, which go in braces after any positional ones. There is no declaration for a record type. The records page says the set of fields, their types and their names make up the record’s shaperecord shape: The number of positional fields of a record, the names of its named fields and the type of every field. The shape alone decides a record's type., and the shape alone decides the type. The next two programs test which names count. The first gives Pune’s coordinates to a variable whose fields have other names:

void main() {
  ({double lat, double lng}) pune = (lat: 18.52, lng: 73.86);
  ({double latitude, double longitude}) sameCity = pune;
  print(sameCity);
}

named_shape.dart:3:52: Error: A value of type '({double lat, double lng})' can't be assigned to a variable of type '({double latitude, double longitude})'.
  ({double latitude, double longitude}) sameCity = pune;
                                                   ^

The compiler refused it: the value typed ({double lat, double lng}) cannot be stored in a variable typed ({double latitude, double longitude}). Renaming a named field makes another type. Names on positional fields work differently:

void main() {
  (int paise, int quantity) line = (2500, 2);
  // The names in a positional record type are only documentation:
  (int quantity, int paise) relabelled = line;
  print('relabelled.\$1 = ${relabelled.$1}');
  print('same value: ${relabelled == line}');
}

relabelled.$1 = 2500
same value: true

(int paise, int quantity) went into (int quantity, int paise) without a word, and relabelled.$1 still printed 2500, the price. The compiler matched the fields by position, and the names were a note for the reader. So when two positional fields have the same type, nothing stops a caller from reading them the wrong way round; with named fields, every read says which field it means. This table sums up which changes make a new record type:

A long record type is tiring to repeat, so give it a name with a typedeftypedef: A named alias for a type, most often a function type, such as typedef Validator = String? Function(String). It documents intent and keeps declarations readable; it creates no new class. More in “Closures, function types and tear-offs”. txn.dart names the shape of a payment and uses that name in a function’s signature:

typedef Txn = ({String id, int amountPaise, String vpa});

Txn refund(Txn t) => (id: '${t.id}-R', amountPaise: -t.amountPaise, vpa: t.vpa);

void main() {
  final Txn paid = (id: 'T42', amountPaise: 25000, vpa: 'asha@okbank');
  final back = refund(paid);
  print(back);

  // The alias and the written-out type are one and the same type.
  ({String id, int amountPaise, String vpa}) plain = back;
  print('plain is Txn: ${plain is Txn}');
}

(amountPaise: -25000, id: T42-R, vpa: asha@okbank)
plain is Txn: true

refund takes and returns a Txn, and plain is Txn printed true: the alias and the written-out record type are one type, which is how the typedefs page describes every alias. The printout listed the fields as amountPaise, id and vpa, sorted again rather than in the order written.

Records with equal fields are equal

equality.dart makes two records for one postcode, one from a literal and one from a sum, and then compares several pairs:

void main() {
  final pin = 411000 + 1;
  final a = ('Pune', 411001);
  final b = ('Pune', pin);
  print('a == b: ${a == b}');
  print('equal hash codes: ${a.hashCode == b.hashCode}');

  final x = (city: 'Pune', pin: 411001);
  final y = (pin: 411001, city: 'Pune');
  print('named fields in another order: ${x == y}');

  final tags = ['veg', 'jain'];
  print('one list in both: ${('Thali', tags) == ('Thali', tags)}');
  final p = ('Thali', ['veg', 'jain']);
  final q = ('Thali', ['veg', 'jain']);
  print('two equal lists: ${p == q}');

  final order = ('Thali', tags);
  tags.add('no onion');
  print(order);
}

a == b: true
equal hash codes: true
named fields in another order: true
one list in both: true
two equal lists: false
(Thali, [veg, jain, no onion])

a == b printed true, and the two hash codes were equal too, although the records are separate objects made in different ways. The records page gives the rule: two records are equal when they have the same shape and their corresponding fields have equal values. That is structural equalitystructural equality: Equality decided by contents rather than by object: two records are equal when they have the same shape and every pair of corresponding fields is equal., and every record gets it, together with a matching hashCode, without a line of code from you. Since the order of named fields is not part of the shape, the third comparison printed true as well.

The fourth and fifth lines look alike but disagree. Step through what == did for p == q, the pair that printed false:

A record compares its fields with each field’s own ==, so the result is only as good as that operator. List’s documentation says lists “are, by default, only equal to themselves”, which is reference identityreference identity: Whether two references lead to one and the same object. identical() checks it and no class can change its answer; == checks it too unless the class overrides ==. More in “Operators, cascades and equality in Dart”: one shared list made the records equal, two lists with the same elements did not. The last line shows a second consequence. After tags.add('no onion'), the record printed the new element: a record cannot point a field at another object, but the object a field holds can still change.

Equal records find the same map entry

A cinema keeps its bookings in a map from seat to name, and the key of each entry is a record with a row and a seat number. seat_map.dart books two seats, looks them up with records built later, and collects picked seats in a set:

void main() {
  final booked = <({String row, int seat}), String>{};
  booked[(row: 'B', seat: 12)] = 'Asha';
  booked[(row: 'B', seat: 13)] = 'Ravi';

  // A new record with equal fields finds the same entry.
  final wanted = (row: 'B', seat: 6 * 2);
  print('B12 is booked by ${booked[wanted]}');
  print('B13 taken: ${booked.containsKey((seat: 13, row: 'B'))}');
  print('B14 taken: ${booked.containsKey((row: 'B', seat: 14))}');

  final picked = {
    (row: 'C', seat: 1),
    (row: 'C', seat: 1),
    (row: 'C', seat: 2),
  };
  print('${picked.length} different seats: $picked');
}

B12 is booked by Asha
B13 taken: true
B14 taken: false
2 different seats: {(row: C, seat: 1), (row: C, seat: 2)}

Each lookup in the output built a new record, and each found the entry stored earlier, or none:

The LinkedHashMap documentation explains why this works: a map literal such as booked is a LinkedHashMap, which finds entries in a hash table, so its keys need an == and a hashCode that agree, with equal hash codes for equal keys. The records specification requires exactly that of records, which makes any record whose fields compare soundly, such as strings and ints, a dependable key. The seat (row: 'B', seat: 6 * 2) was computed at run time and still matched, and the set dropped the repeated C1 without being told to.

One function can return several values in a record

Back to the five readings from the start. min_max.dart returns the lowest and the highest reading together:

(int, int) minMax(List<int> xs) {
  var lo = xs.first, hi = xs.first;
  for (final x in xs.skip(1)) {
    if (x < lo) lo = x;
    if (x > hi) hi = x;
  }
  return (lo, hi);
}

void main() {
  final temperatures = [31, 27, 35, 29, 33];
  final (lo, hi) = minMax(temperatures);
  print('lowest $lo, highest $hi');

  final range = minMax(temperatures);
  print('spread ${range.$2 - range.$1} degrees');
}

lowest 27, highest 35
spread 8 degrees

The return type (int, int) promises exactly two ints, and return (lo, hi); builds the record. At the call site, final (lo, hi) = minMax(temperatures); declares two variables in one statement and printed lowest 27, highest 35. That declaration is a pattern, which the destructuring lesson takes apart in full. The second call keeps the whole record and reads it through $1 and $2, which gave the spread of 8 degrees.

The records page puts the alternatives in one sentence: a class is more verbose, and a List or a Map loses type safety. This table compares the ways the same two results can come back:

The last row is the safest when both values have the same type, because a caller writes range.min and cannot mix them up. A record also groups futures of different types so that they can be awaited together, which the asynchronous programming module shows.

A class or a map fits when a record cannot

Records only hold data. as_map.dart stores Pune’s coordinates in a map and in a record, and asks both the same questions:

void main() {
  // The same two values as a map: the keys are strings, checked only at run time.
  final pune = <String, double>{'lat': 18.52, 'lng': 73.86};
  print('misspelt key: ${pune['lattitude']}');

  final again = <String, double>{'lat': 18.52, 'lng': 73.86};
  print('two equal maps ==: ${pune == again}');

  // As a record, the same misspelling would not compile, and equal values are equal.
  final asRecord = (lat: 18.52, lng: 73.86);
  print('two equal records ==: ${asRecord == (lat: 18.52, lng: 73.86)}');
}

misspelt key: null
two equal maps ==: false
two equal records ==: true

The misspelt key 'lattitude' compiled and quietly read null, and two maps with equal entries compared false, because Map keeps the identity == that List has. The record would refuse the misspelling at compile time, and its two equal values compared true. A class sits between them: it is checked like a record, and it can also run code, such as a constructor that refuses a negative amount, which a record never can. Answer the three questions in the table for a piece of data from your own code:

In short: a record for values that only travel together inside your code, such as results, keys and pairs; a class when the data needs methods, checks or a long-lived public type; a map when the field names arrive with the data. The records page adds that a typedef only names a record’s shape, and that only a class gives full abstraction and encapsulation.

Practise: two functions that return records

The package has three files: a pubspec whose one dev dependency is package:test, a library whose two functions still throw UnimplementedError, and a test file whose four sample tests say what those functions must return.

name: practice
description: Two functions that return records, with four sample tests.
publish_to: none

environment:
  sdk: ^3.13.0

dev_dependencies:
  test: ^1.33.0

/// The smallest value, the largest value and the mean of [xs],
/// or null when [xs] is empty.
({int min, int max, double mean})? stats(List<int> xs) {
  throw UnimplementedError('stats');
}

/// Splits a handle such as 'asha@okbank' into its user part and its
/// handle part, or returns null when [vpa] does not follow the rule:
/// exactly one '@', with at least one character on each side.
(String user, String handle)? splitVpa(String vpa) {
  throw UnimplementedError('splitVpa');
}

import 'package:practice/practice.dart';
import 'package:test/test.dart';

void main() {
  test('stats of three readings', () {
    expect(stats([4, 1, 7]), (min: 1, max: 7, mean: 4.0));
  });

  test('stats of no readings is null', () {
    expect(stats([]), isNull);
  });

  test('a handle splits at the @', () {
    expect(splitVpa('asha@okbank'), ('asha', 'okbank'));
  });

  test('a handle without a user part is refused', () {
    expect(splitVpa('@okbank'), isNull);
  });
}

The session prints the starter file and then runs the tests:

from session import files, run

# The practice package as handed out: both functions still throw, so all four sample tests fail.
files("practice=records_practice")
run(
    """
cd records_practice
cat lib/practice.dart
dart pub get --offline > /dev/null
!dart test --reporter failures-only
""",
    pub=True,
)

$ cd records_practice
$ cat lib/practice.dart
/// The smallest value, the largest value and the mean of [xs],
/// or null when [xs] is empty.
({int min, int max, double mean})? stats(List<int> xs) {
  throw UnimplementedError('stats');
}

/// Splits a handle such as 'asha@okbank' into its user part and its
/// handle part, or returns null when [vpa] does not follow the rule:
/// exactly one '@', with at least one character on each side.
(String user, String handle)? splitVpa(String vpa) {
  throw UnimplementedError('splitVpa');
}
$ dart pub get --offline > /dev/null
$ dart test --reporter failures-only
+0 -1: test/practice_test.dart: stats of three readings [E]
  UnimplementedError: stats
  package:practice/practice.dart 4:3  stats
  test/practice_test.dart 6:12        main.<fn>

+0 -2: test/practice_test.dart: stats of no readings is null [E]
  UnimplementedError: stats
  package:practice/practice.dart 4:3  stats
  test/practice_test.dart 10:12       main.<fn>

+0 -3: test/practice_test.dart: a handle splits at the @ [E]
  UnimplementedError: splitVpa
  package:practice/practice.dart 11:3  splitVpa
  test/practice_test.dart 14:12        main.<fn>

+0 -4: test/practice_test.dart: a handle without a user part is refused [E]
  UnimplementedError: splitVpa
  package:practice/practice.dart 11:3  splitVpa
  test/practice_test.dart 18:12        main.<fn>

+0 -4: Some tests failed.

Consider enabling the flag chain-stack-traces to receive more detailed exceptions.
For example, 'dart test --chain-stack-traces'.
[exit status 1]

1. Copy the package into a folder of your own: pubspec.yaml, lib/practice.dart and test/practice_test.dart as above. Run dart pub get and then dart test: all four tests fail, as in the session.
2. Write stats. Return null for an empty list; otherwise build a record with the named fields min, max and mean, where mean is a double.
3. Write splitVpa by the rule in its comment: exactly one ‘@’, with at least one character before and after it. Return a record of the two parts, or null.
4. Run dart test until it ends with “All tests passed!”. Then add tests of your own for one reading, for negative readings, and for ‘a@’, ‘a@b@c’ and an empty string, and make them pass.

Once all four sample tests pass, check what stayed with you from each section:

Interview questions

Warm-up (fresher): Two records hold the same values. When does == call them equal, and why does that make them safe map keys?

A record compares by contents, not by object. == first checks that the other value is a record of the same shape, the same number of positional fields and the same named fields, and then compares the matching fields with their own ==. The order in which named fields were written does not matter. Records also produce a hash code from their fields, so two equal records always hash alike, and a map or a set needs exactly that to find a key again: a record built later with the same row and seat finds the stored booking. The answer is only as good as the fields’ own equality, though. A field holding a List compares by identity, so two records with equal but separate lists are not equal, and such a record finds nothing when used as a key.

Two longer questions from the module’s bank build on this lesson:

Key takeaways

• A record bundles a fixed set of positional and named fields into one immutable value; positional fields are read as $1, $2 and so on, named ones by their names, and a record with one positional field needs a trailing comma.
• A record’s type is its shape: the number of positional fields, the names of named fields and every field’s type, while names written on positional fields are documentation and a typedef only gives a shape a second name.
• Two records count as equal when their shapes match and every field is equal, each compared with its own ==, so a field holding a List compares by identity and can still change inside the record.
• Records give matching == and hashCode, which makes records of strings and numbers dependable map keys and set elements, as the seat map showed.
• A record return type such as (int, int) or ({int min, int max}) returns several typed values without a class; choose a class when the data needs code or a long-lived public type, and a map when names come from the data.