Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation of Uint8List.operator + is incorrect. It returns a List<int>. #51034

Open
whesse opened this issue Jan 17, 2023 · 0 comments
Open
Assignees
Labels
area-core-library SDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries. library-typed-data type-documentation A request to add or improve documentation

Comments

@whesse
Copy link
Contributor

whesse commented Jan 17, 2023

The documentation of Uint8List.operator + says that if both operands are Uint8List, it returns a Uint8List.
This is incorrect, it always returns a List.

The documentation says:

"Returns a concatenation of this list and other.

If other is also a typed-data list, then the return list will be a typed data list
capable of holding both unsigned 8-bit integers 
and the elements of other, otherwise it'll be a normal list of integers."

That this means it can return a Uint8List is made clear by the note in the documentation of List.operator +, that says:

"Returns a new list containing the elements of this list followed by the elements of other.

The default behavior is to return a normal growable list. Some list types
may choose to return a list of the same type as 
themselves (see [Uint8List.+](https://api.dart.dev/stable/2.18.7/dart-typed_data/Uint8List/operator_plus.html));

From the beginning, when this method was added to Uint8List in https://dart-review.googlesource.com/c/sdk/+/39140
, the method did not return a Uint8List, but inherited its implementation through _TypedIntList, https://dart-review.googlesource.com/c/sdk/+/39140/4/sdk/lib/typed_data/typed_data.dart#386 , which has since been replaced by a mixin.

I think the implementation of these classes should be changed so that this documentation is true, but until then, the
documentation should be correct.

This override of Uint8List.operator + is also not present on Int8List or other similar classes. Only Uint8 has it.

@whesse whesse added area-documentation Prefer using 'type-documentation' and a specific area label. library-typed-data labels Jan 17, 2023
@devoncarew devoncarew added area-core-library SDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries. type-documentation A request to add or improve documentation and removed area-documentation Prefer using 'type-documentation' and a specific area label. labels Apr 16, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-core-library SDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries. library-typed-data type-documentation A request to add or improve documentation
Projects
None yet
Development

No branches or pull requests

3 participants