List.single属性的主要用途是什么？

Question

Some days ago, I noticed that Dart's List class has the single property. Then, I read an official API document, and understood how this property works. This mean I know that List.single works as follows:

print(['a'].single);     // outputs 'a'
print(['a', 'b'].single) // throws StateError

But I cannot find any practical use case of the single property. Childish codes showed above make no sense in actual programming, of course.

What is the purpose of the property? Why does this property throw an Exception if a List contains two or more elements? Why is it not a boolean property which stands for whether a List has only single element? How do Dart Language developers think it is useful to include List.single in the core API?

If you have any knowledge about this, I would appreciate it very much if you give me a hand.

Answer 1

You can use single in case you expect an Iterable to only contain one element. Here is a real world example: We have database connection that has query method to execute a SQL queries. The method returns the rows affected by the query. Now consider a query where you only expect exactly one line to be affected:

var row = databaseConnection.query('SELECT * FROM xyz WHERE id=5').single;

This gives a short way of failing in case no or more then one line are affected. Sure, one could also write:

var rows = databaseConnection.query('SELECT * FROM xyz WHERE id=5');

if (rows.length != 1) {
  throw new StateError('Something is wrong');
}

var row = rows.first;

But this is much longer. Alternatively you may want to assert .

As List implements Iterable , it also contains single . The single getter is also useful for streams, if you expect exactly one element. Consider the same example as a Stream of rows:

databaseConnection.query('SELECT * FROM xyz WHERE id=5').single.then((row) {
  print('Process the row');
});