File.readAsBytes should return Uint8List

[tvolkert]

File.readAsBytes (and the sync version as well) should return Uint8List rather than List<int>. This is a backwards-compatible change since Uint8List implements List<int>.

@zanderso

[zanderso]

The implementation already returns a Uint8List upcast to a List<int>.

[tvolkert]

Awesome. Any reason not to declare that in the API?

[zanderso]

I don't know. /cc @lrhn @floitschG

[tvolkert]

Here's the use case: I'm reviewing code that defines a new API for comparing binary images as bytes. The API currently takes List<int> for each image's bytes, and in my review, I stated that they should take Uint8List instead. However, if they do that, then callers will have to take the results of File.reasdAsBytes and then call new Uint8List.fromList(bytes) because they can't assume that they already have a Uint8List. They should be able to know that they're receiving a Uint8List from File.reasAsBytes

[tvolkert]

Also, File implementations shouldn't ever be allowed to return a List<int> that's not a Uint8List.

[lrhn]

I would recommend changing the API to state that the byte list is a Uint8List, unless there is a good reason not to.

There are two dangers with saying List<int> and always returning Uint8List:

1. People doing roundabout things to make it Uint8List, or
2. People starting to depend on it being Uint8List.

In the latter case, someone might try to mock the class fail to return a Uint8List. In the former case, you get unnecessary overhead.
Or, in other words, "under-promise, over-deliver" is not a good way to design APIs :)

There is one danger with saying Uint8List: You may end up in a situation in the future where you try to implement the interface, and your bytes are not in a Uint8List, so you have to copy them then.

I don't think that last danger is an actual problem. That kind of issue only tends to crop up in testing, and performance isn't the same issue there.

[matanlurey]

+1. For example, implementing Flutter's AssetBundle class requires ByteData (https://docs.flutter.io/flutter/services/AssetBundle/load.html). I rely on an upcast from List<int> to ByteData now, but that looks... really weird:

import 'dart:io';

import 'package:flutter/services.dart';
import 'package:path/path.dart' as p;

/// A simple implementation of [AssetBundle] that reads files from an asset dir.
/// 
/// This is meant to be similar to the default [rootBundle] for testing.
class DiskAssetBundle extends CachingAssetBundle {
  final Directory _assetPath;

  DiskAssetBundle([Directory assetPath])
      : _assetPath = assetPath ??
            Directory(
              p.join(Directory.current.path, 'assets'),
            ),
        assert(_assetPath.existsSync(), 'Asset folder expected');

  @override
  Future<ByteData> load(String key) {
     return File(p.join(_path, key))
        .readAsBytes()
        .then((data) => ByteData.view(data as ByteBuffer));
  }
}

[dkashkin]

+1! Whenever I think about binary data "int" and "Uint8" are not the same animal. The semantics of Dart code should make it clear that we're talking about Uint8 all the way.

[jamesderlin]

It seems like everybody agrees that this should be done, and nobody's given any reasons not to do it nor described any potential problems. Is there anything holding this up?

[tvolkert]

https://dart-review.googlesource.com/c/sdk/+/101742

[tvolkert]

Breaking change request: #36900

[tvolkert]

This is done now.