Make encode reusable in Phobos

[edi33416]

This PR adds two overloads to encode so those can be called from std.utf.encode (see here)

This PR depends on #2403

[dlang-bot]

Thanks for your pull request and interest in making D better, @edi33416! 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 annotated coverage diff directly on GitHub with CodeCov's browser extension
• 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 fetch digger
dub run digger -- build "master + druntime#2404"

[andralex]

Great idea. Let's define this function for all inputs (no contracts, no assert(isValidDChar)) and have it return 0 upon bad dchar. Then higher-level functions can throw exceptions, use replacement char etc.

[Geod24]

Additionally, instead of returning a length, return a slice to the buffer, or null on bad dchar, because the next thing people will need to do is slice that buffer.
Returning null and not an empty slice is important, because otherwise if (auto s = encode(...)) will always be true.
Lastly, since this piece of code is highly performance sensitive, did you inspect the assembly to make sure out does not get default-initialized on function entry ?

[jacob-carlborg]

Isn't it better to pass buf as a regular char[] to push the allocation choice to the caller? If the caller wants to pass a static array, the array can be sliced to be able to pass it as char[].

[WalterBright]

= void;

[WalterBright]

= void;

[WalterBright]

Not a fan of the following functions because:

1. They are an overload of the previous encode functions, but do something fundamentally different
2. They rely on the GC. We should be crafting functions that do not allocate, but instead send the characters to a sink or an output range.

[jacob-carlborg]

Exactly: #2404 (comment).

[jacob-carlborg]

Also, is this the right order of arguments for UFCS? Would it be better to pass c first?

[WalterBright]

The sink normally is the first argument, as in:

sink.put(c);

[RazvanN7]

@edi33416 Are you willing to take this to the finish line?