Add doc aliases for memory allocations

[yoshuawuyts]

This patch adds doc aliases for various C allocation functions, making it possible to search for the C-equivalent of a function and finding the (safe) Rust counterpart:

• Vec::with_capacity / Box::new / vec! -> alloc + malloc, allocates memory
• Box::new_zeroed -> calloc, allocates zeroed-out memory
• Vec::{reserve,reserve_exact,try_reserve_exact,shrink_to_fit,shrink_to} -> realloc, reallocates a previously allocated slice of memory

It's worth noting that Vec::new does not allocate, so we don't link to it. Instead people are probably looking for Vec::with_capacity or vec!. I hope this will allow people comfortable with the system allocation APIs to make it easier to find what they may be looking for.

Thanks!

[rust-highfive]

r? @joshtriplett

(rust_highfive has picked a reviewer for you, use r? to override)

[joshtriplett]

This is a great idea!

For calloc, it isn't just used to allocate zeroed memory; it's also used to allocate arrays of structures, since it takes a number of elements and a size for each element. So, I think it'd be appropriate for calloc to lead to Vec::with_capacity as well.

Also consider aliases for alloc, calloc, and malloc on String::with_capacity.

I'd love to see PRs like this for other common C functions as well, such as the str* family of string functions, and the mem* family of memory functions. For instance, strcmp and memcmp could point to the documentation for Ord and Eq (the portions that mention the corresponding operators). (Those can be separate PRs; the only changes I'm requesting in this PR are the additional aliases for String::with_capacity and the additional alias for calloc.)

[yoshuawuyts]

I've updated with @joshtriplett's feedback.

@Manishearth @GuillaumeGomez did you resolve the conversation in #79211? -- I'm tempted to tag both libs and docs on this for review, but wanted to check before doing so.

[Manishearth]

@yoshuawuyts yeah mostly "ping both @GuillaumeGomez and the libs team for doc changes". Hopefully they can form a libs-docs team eventually.

Feel free to tag the docs team, it's just kinda defunct right now and you'd be tagging more people than you need.

[GuillaumeGomez]

No need. Just doc-alias is enough (so we can keep track of the usage of the feature in case we need to debug something).

[yoshuawuyts]

Got it, thanks heaps!

[bors]

☔ The latest upstream changes (presumably #80530) made this pull request unmergeable. Please resolve the merge conflicts.

[crlf0710]

Triage: there's merge conflicts now.

[yoshuawuyts]

Oh dang, this is because of the new allocator_api methods isn't it? I'm out of time to address these changes today, but I'll try and squeeze them into next week Friday.

[yoshuawuyts]

Resolved the merge conflicts; a simple rebase was enough. This is again ready for review!

[GuillaumeGomez]

Even though this realloc alias makes sense, having so many of it is kinda killing its purpose, no?

[yoshuawuyts]

Rust has no canonical "realloc" function; instead it's split up between various different methods which perform specific kinds of reallocations. Someone searching for "realloc" may not be aware of this, and sharing the various ways in which vectors can be reallocated may be helpful.

Conversely an experienced Rust programmer may not recall the exact name of a specific reallocation they're trying to perform (or may want to validate whether a vec method indeed reallocates) and searching for "realloc" may provide them with an answer.

[GuillaumeGomez]

Fine by me, let's give it a try like this then!

[GuillaumeGomez]

Thanks!

@bors: r+

[bors]

📌 Commit 7d10238 has been approved by GuillaumeGomez

[bors]

⌛ Testing commit 7d10238 with merge 34b3d41...

[bors]

☀️ Test successful - checks-actions
Approved by: GuillaumeGomez
Pushing 34b3d41 to master...