WIP improve List.reserve docs - #10852
Conversation
Greptile SummaryExpands the built-in API documentation for list capacity management and adds corresponding guidance to
Confidence Score: 4/5The PR appears safe to merge after correcting the non-blocking inaccuracies in the documented allocation semantics. The executable implementation is unchanged, but the new public documentation incorrectly promises exact capacity in a reachable reserve case and unconditional allocation-and-copy behavior. Files Needing Attention: src/build/roc/Builtin.roc
|
| Filename | Overview |
|---|---|
| src/build/roc/Builtin.roc | Documentation-only changes substantially clarify reserve usage, but two categorical allocation claims do not hold for all implementation paths. |
Reviews (1): Last reviewed commit: "improve List.reserve docs" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ## `reserve(spare)` sizes the allocation to hold exactly `List.len(list) + spare` | ||
| ## items; it trusts the request instead of rounding it up. If the list is not | ||
| ## shared and already has room for `spare` more items, it does nothing. | ||
| ## Otherwise it always performs a heap allocation and copies the existing items | ||
| ## into it. |
There was a problem hiding this comment.
The documentation promises that reserve(spare) always allocates exactly List.len(list) + spare capacity and copies the existing items, but reserving one slot on a full exclusive list invokes geometric growth, while allocator reallocation can extend storage in place without copying. Users therefore cannot rely on either guarantee when reasoning about capacity or allocation costs.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
|
Isn’t it a bit verbose in contrast to the other docs? |
2 participants
No description provided.