improve documentation of SortedRange.release

[dkorpel]

Because it came up on the forum that the documentation of release is not informative: When should I use SortedRange.release?

[dlang-bot]

Thanks for your pull request and interest in making D better, @dkorpel! We are looking forward to reviewing it, and you should be hearing from a maintainer soon.
Please verify that your PR follows this checklist:

• My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
• My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
• I have provided a detailed rationale explaining my changes
• New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

---

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub run digger -- build "master + phobos#8066"

[RazvanN7]

A rebase will most likely get rid of the tester failures.

[RazvanN7]

I think that adding:

assert(a == sort!"a < b"([1, 2, 3]));

Might clarify that a is a sorted range, whereas release simply extracts the underlying array.

[RazvanN7]

hm... both circleCI and buildkite failt phobos with:

std/typecons.d(1246): Error: `TypeInfo` cannot be used with -betterC

This obviously has nothing to do with this PR.

[RazvanN7]

Hmm, it looks like the error might not be spurious after all. Could you try commenting out the unittest to see if the autotester still fails?

[RazvanN7]

@dkorpel What happened with the testing pipeline when the unittest was commented?

[dkorpel]

It was all green with the test commented out

[dkorpel]

And now it's red again. I don't understand what's buildkite's problem with Phobos, the log ends in:

0.000s PASS release64 std.internal.scopebuffer
0.001s PASS release64 std.internal.test.dummyrange
0.000s PASS release64 std.internal.test.range
0.000s PASS release64 std.typetuple
make[1]: Leaving directory '/var/lib/buildkite-agent/builds/ci-agent-3ff56b73-5108-4d1c-a54b-acc66981efad-8/dlang/phobos/phobos'
rm generated/linux/release/64/betterctests/.directory
🚨 Error: The command exited with status 2

So it fails to remove the betterC tests?

[RazvanN7]

It's the same as circleCI. My assumption is that the test should be @BetterC

../dmd/generated/linux/release/64/dmd  -conf= -I../druntime/import  -w -de -preview=dip1000 -preview=dtorfields -m64 -fPIC -O -release -defaultlib= -debuglib= -L-lpthread -L-lm -betterC -unittest -run generated/linux/release/64/betterctests/std_range_package.d
--
  | std/typecons.d(1246): Error: `TypeInfo` cannot be used with -betterC
  | posix.mak:668: recipe for target 'std/range/package.betterc' failed

[MoonlightSentinel]

It's the same as circleCI. My assumption is that the test should be @BetterC

Yes, the unittest is nested in SortedRange and hence pulled into the @BetterC test declared here.

Use a static array instead of a dynamically allocated one and it should pass the test.

[dkorpel]

Yes, the unittest is nested in SortedRange and hence pulled into the @BetterC test declared here.

Ugh, this is why I never use nested unittests. I wish there was a way to make a top-level unittest work like a DDoc code example for a member function.

[dkorpel]

It's still failing. Is there a way to see the circleci build log without giving them complete read/write access to all my private repositories?

[MoonlightSentinel]

std/typecons.d(1246): Error: `TypeInfo` cannot be used with -betterC
posix.mak:668: recipe for target 'std/range/package.betterc' failed

You can run these tests locally,

Run all betterC tests

make -f posix.mak betterc

Only the failing test:

make -f posix.mak std/range/package.betterc

[RazvanN7]

generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4file8DirEntry6isFileMFNdNfZb'
--
  | generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4file8DirEntry4nameMxFNaNbNdNfZAya'
  | generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4file8DirEntry4nameMxFNaNbNdNfZAya'
  | generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4file8DirEntry4nameMxFNaNbNdNfZAya'
  | generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4file8DirEntry4nameMxFNaNbNdNfZAya'
  | generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4path12absolutePathFNaNfAyaLQeZQh'
  | generated/linux/release/64/benchmark.o:benchmark/runbench.d:function _D8runbench8runTestsFSQu6ConfigZv: error: undefined reference to '_D3std4path12absolutePathFNaNfAyaLQeZQh'

I'm fairly certain that after this last rebase, this will be good to go.

[dkorpel]

CircleCI and buildkite are happy now, so it's Azure's turn to error out:

std.utf.UTFException@D:\a\1\dmd\ldc2-1.23.0-windows-multilib\bin\..\import\std\utf.d(1507): Invalid UTF-8 sequence (at index 1)
----------------
0x002B7E0B in ulong[] core.sys.windows.stacktrace.StackTrace.traceNoSync(uint, core.sys.windows.winnt.CONTEXT*)
0x002B7BC2 in core.sys.windows.stacktrace.StackTrace core.sys.windows.stacktrace.StackTrace.__ctor(uint, core.sys.windows.winnt.CONTEXT*)
0x002ABA9D in object.Throwable.TraceInfo core.runtime.defaultTraceHandler(void*)

[RazvanN7]

That was an unexpected ride for a documentation PR. Thanks for your patience @dkorpel !