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.