dotnet / dotnet/dotnet-api-docs

`Stream.Length` docs ambiguous

Open
#10,069 3 comments 0 reactions 0 assignees View on GitHub
area-System.IO Pri3 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

The docs for `Stream.Length` currently say:

> When overridden in a derived class, gets the length in bytes of the stream.

This is ambiguous, in the sense that I felt the need to spin up `dotnet fsi` to confirm to myself that I had picked the correct interpretation. Does it mean "the *remaining* length", or "the *absolute* length"? Of course it means "absolute", and most people will probably choose that interpretation anyway, but in a scenario where the `Stream` represents "forgetting everything that came before", it may be natural to interpret it as "remaining" (because the `Stream` has forgotten its past!).

I don't have a *great* suggestion for an improvement, but perhaps a remark to the effect that "in a stream which supports `Seek`, this is expected essentially to be the value of `Position` after `Seek(0L, SeekOrigin.End)`"? (`Position` is much more natually an absolute concept, because you can `Seek` backwards.) Or perhaps "When overridden… gets the total length in bytes of the stream"?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.