Proposed Changes to the Range API for Phobos v3

[Imperatorn]

On Thursday, 16 May 2024 at 14:56:55 UTC, Jonathan M Davis wrote:
> Okay. This is my proposal for an updated input range API for 
> Phobos v3. I previously sent it out to some or the core D 
> folks, and the feedback has largely been positive, but I'm now 
> posting it to the newsgroup for wider feedback.

Tales from the AI
-----------------

General Observations:
Length and Clarity:

The proposal is very long and dense, which might deter some 
readers from providing thorough feedback. Consider breaking it 
into more manageable sections or providing a summarized version 
at the beginning.

Some sections could benefit from more concise language. Removing 
redundant phrases and focusing on the core points could enhance 
readability.
Implementation Details:

You mention several times that the exact details need to be 
sorted out. It would be beneficial to provide more concrete 
examples or pseudo-code where possible to clarify your ideas.

Specific Observations and Suggestions:

Auto-decoding:

Your point about auto-decoding is clear, but ensure you emphasize 
the impact on backward compatibility. This change might break a 
lot of existing code, so highlighting strategies for a smooth 
transition would be beneficial.
Save Requirement for Forward Ranges:

You propose removing save and instead relying on copy semantics. 
While this can simplify the API, it's important to provide more 
detailed guidelines on how to implement forward ranges under this 
new requirement. Examples of how to handle common use cases 
without save would help clarify this change.
Copy Semantics for Basic Input Ranges:

Making basic input ranges non-copyable is a significant change. 
Ensure you clearly articulate the benefits versus the drawbacks. 
You might also want to provide migration strategies or helper 
functions for common patterns that currently rely on copying 
input ranges.

Default Initialization:

Requiring all default-initializable ranges to have a valid init 
value is a good move towards safety. However, the discussion on 
whether to disallow finite ranges from disabling default 
initialization seems unresolved. A more definitive stance would 
strengthen the proposal. Consider detailing specific examples of 
how this requirement improves robustness and how to handle 
exceptions.

Transient Front:

Explicitly disallowing transient fronts is a significant change. 
It might help to provide more context or examples of how common 
use cases will be handled under the new rules. For instance, what 
are the alternatives for ranges that currently rely on transient 
fronts?

Const Ranges:

The problem with const ranges is well-articulated, but the 
solution proposed (relying on language improvements) seems 
uncertain. It might be useful to outline potential workarounds or 
interim solutions until language changes are implemented.
Renaming Range API Functions:

Renaming functions like front to first and empty to isEmpty could 
introduce a significant learning curve. Ensure you provide strong 
justifications for these changes and perhaps include a transition 
plan or tools to help developers update their codebases.

Backward Compatibility and Transition Plan:

The proposal introduces many breaking changes. A detailed 
transition plan, including deprecation strategies, versioning 
schemes, and tooling support, would be crucial. Consider 
providing scripts or automated tools to help developers migrate 
their code.

Structural Suggestions:

Summary Section:

Add a summary section at the beginning that lists the key changes 
and their benefits. This helps readers quickly grasp the main 
points before diving into the details.
Separate Concerns:

Consider separating the proposal into multiple documents or 
sections: one for identifying problems with the current API, one 
for the proposed changes, and one for implementation strategies 
and examples.

Examples and Use Cases:

Throughout the document, add more concrete examples and use 
cases. This helps in understanding the practical implications of 
the changes and provides a clearer picture of the benefits and 
challenges.

Community Feedback:

Encourage community feedback by posing specific questions or 
areas where input is particularly needed. This can help focus the 
discussion and gather more targeted feedback.
Overall, your proposal is comprehensive and addresses many 
crucial aspects of the range API. By refining the structure and 
providing more concrete details, you can enhance its clarity and 
make it easier for the community to provide valuable feedback.