Add doc aliases for a lot of the C standard library

[jyn514]

I took the very scientific approach of "ask some friends what parts of
the standard library they use a lot". They suggested
https://www.tutorialspoint.com/c_standard_library/ and also the short
list strcpy, strncpy, memcpy, memcpy, printf, scanf, fprintf, sprintf, asprintf, sscanf, strtok, strntok, malloc, calloc, free, strdup, strndup, err, errx. Many of these already have aliases; those with
*n* have no analogy in rust; asprintf, err, and errx have no analogy in Rust.
I added most of the rest.

[rust-highfive]

r? @KodrAus

(rust-highfive has picked a reviewer for you, use r? to override)

[jyn514]

This one is moderately iffy because you have to pass a radix of 16, but it's close enough.

[jyn514]

I'm very surprised someone added delete but not free.

[camelid]

This alias does seem very reasonable to add.

[jyn514]

I figured these were all "close enough" since int and long don't have a fixed size.

[jyn514]

This one is iffy, but C doesn't really have a split function and I didn't know where else to put strtok.

[jyn514]

This could also go under spawn(). In C system blocks but returns no value.

[camelid]

Do people really search the Rust standard library using C function names?

[jyn514]

@camelid there are existing aliases for malloc, calloc, memcpy, and memmove, among others.

[camelid]

Just because there are existing ones doesn't mean we should add more 🙃

[jyn514]

I think this would be useful if you're learning rust coming from C. format and drop in particular are hard to find if you don't know what they're called - I've seen several people looking for a "drop keyword" without realizing it was in the standard library. I agree the functions on str might not be pulling their weight, but I don't think they're useless either. These aliases are very low cost to add and basically zero to maintain.

[camelid]

format and drop in particular are hard to find if you don't know what they're called - I've seen several people looking for a "drop keyword" without realizing it was in the standard library.

I can understand that, but that's true of many things. For example, I imagine many people will at least start learning Rust from the Book and Rust by Example (those are some of the ways I started). But perhaps others will jump right in without looking at any language-level docs.

These aliases are very low cost to add and basically zero to maintain.

That's true, but I just feel worried that we'll end up littering them all over the place and then not be able to remove them.

[joshtriplett]

asprintf does have an equivalent: format!

[ojeda]

A few nitpicks:

• asprintf, err and errx are not part of C (or even POSIX).
• strdup and strndup will likely be part of C23, but currently are only POSIX.
• strntok does not exist.
• I wouldn't say "most of the C standard library" since there are many, many more functions there! :-) For instance, we are missing all the math.h aliases.

Related: if we are going to add aliases for several languages (C, Python, Java...), it would be great if the alias functionality could take a lang parameter (or source or from or something like that) to be able to categorize the aliases and tell where they come from. This would be good for documentation and could be used in the future to let the user filter/search/list by them, e.g.:

#[doc(alias = "sprintf", lang = "C, C++, POSIX")]

[ojeda]

C does not have nil, and null should be NULL if it is referring to the library side of C.

[jyn514]

I can separate this into a separate PR if you like, but I think the aliases are useful.

null should be NULL if it is referring to the library side of C.

doc(alias) is case insensitive.

[ojeda]

Still, writing the original name would be better, no? Otherwise we should change e.g. Map to map in the Java one, etc.

[ojeda]

I mean, I guess you want to keep null for other languages that use that one -- again, this depends on how we are looking at this: whether we are trying to keep a mapping or just search terms for any language that matches. If the latter, I agree: null is better.

[ojeda]

If we are adding these, then we should also add:

• _Bool and bool for bool.
• The exact-width integer types: int8_t, uint8_t, etc.
• char32_t for char.
• ssize_t for isize (POSIX, but common enough).
• Perhaps float and double for f32 and f64 (not guaranteed, but likely).

[jyn514]

_Bool and bool for bool.

I have the same question as in #81989 (comment) - what do you see as the point of doc(alias)? Both of those pull up bool as the first result in search already: https://doc.rust-lang.org/stable/std/?search=_Bool, https://doc.rust-lang.org/stable/std/?search=bool

The others look useful to add, thanks :)

[ojeda]

See my answer to that comment.

You're welcome! :)

[jyn514]

Related: if we are going to add aliases for several languages (C, Python, Java...), it would be great if the alias functionality could take a lang parameter (or source or from or something like that) to be able to categorize the aliases and tell where they come from.

Can you open an issue for this?

[jyn514]

strdup and strndup will likely be part of C23, but currently are only POSIX.

I didn't distinguish very much between "standard C" and "POSIX", I think they're both helpful. Happy to add a bunch more aliases from posix if you think they'd be useful :)

[ojeda]

Related: if we are going to add aliases for several languages (C, Python, Java...), it would be great if the alias functionality could take a lang parameter (or source or from or something like that) to be able to categorize the aliases and tell where they come from.

Can you open an issue for this?

Of course -- done! #82000

[KodrAus]

At this stage I think I echo @camelid's concern about collecting an unbounded number of aliases that aren't necessarily all useful to have.

I think that applies more to the string aliases than the others, which do seem pretty useful. Maybe we should look at landing this without:

• string.rs
• char/methods.rs
• num/mod.rs
• str/mod.rs

aliases. What do you all think?

[JohnCSimon]

@jyn514 ping from triage - please address the merge conflicts, thanks.
@rustbot label: -S-waiting-on-review +S-waiting-on-author

[jyn514]

I think that applies more to the string aliases than the others, which do seem pretty useful. Maybe we should look at landing this without: ... what do you think?

Sure, that seems good to me :)

[m-ou-se]

We briefly discussed this in the libs meeting, see: #81989 (comment)

Some more thoughts related to the kind of aliases in this PR:

The Rust standard library reference is probably not the place to explain uint16_t is called u16 in Rust, or that one can just .clone() a String instead of calling strdup. (But as said in the linked comment, we're open for ideas for a policy here.)

Aliases can provide no context or explanation, which might lead to confusion or might even come across as somewhat passive aggressive: E.g. someone looking for the raw deallocation api searching for free or delete would now end up with mem::drop, as if the search results are saying "no you don't want to manage your own memory, just drop things!". The explanation that in Rust we usually use types with a Drop implementation instead of manual malloc/free calls probably belongs in a place that explains that whole concept, not just in a doc alias.

Even for seemingly obvious aliases such as toupper it's not clear where it should go: If by entering toupper in the search bar the user meant "what's the equivalent of toupper() from C?", then to_ascii_uppercase is the right answer. But if the question was "how do I make things uppercase? 'toupper' or something?", then to_uppercase is the right answer.

Those of us who were in the meeting agreed that questions like "what's the closest Rust thing to $thing from $language?" are better answered by some kind of cheatsheet or blog post or other resources maintained by the community. We don't know enough about all languages to be able to maintain this as part of the standard library.

I personally think some kind of policy for doc aliases in the standard library could be something like "it's okay to add alias $x to $y if someone reasonable expects $y to be named $x in Rust". E.g. the popcnt alias on u32::count_ones. But someone looking for strdup is probably looking for libc::strdup and not unaware of the concept of clone()ing things.

But as I said in the linked comment, we'd first like to see some kind of write down of such a policy proposal and reach a consensus before accepting more doc alias PRs.

(I'll put it on my own to-do list to write a draft for it, but I'm probably not going to have time for that any time soon.)

[jyn514]

Aliases can provide no context or explanation, which might lead to confusion or might even come across as somewhat passive aggressive: E.g. someone looking for the raw deallocation api searching for free or delete would now end up with mem::drop, as if the search results are saying "no you don't want to manage your own memory, just drop things!". The explanation that in Rust we usually use types with a Drop implementation instead of manual malloc/free calls probably belongs in a place that explains that whole concept, not just in a doc alias.

It seems inconsistent to have an alias for delete but not for free. I don't think "just drop things" is substantially different from free - there's no direct equivalent of malloc, so if you really don't understand RAII it will become clear when you try to construct something on the heap and realize you have to use Box or Global::alloc when no one else is using them.

That said, I agree most of the changes here are not super useful.

[ojeda]

Aliases can provide no context or explanation, which might lead to confusion or might even come across as somewhat passive aggressive

I suggested somewhere else to have some extra data for each alias. This was in the context of explaining which language the alias came from (since e.g. same typenames have different meanings in different languages), but having a "reason" or "comment" field overall per alias seems like a good idea to solve the "no context" issue you mention (even if we don't end up with aliases for different languages).

[m-ou-se]

It seems inconsistent to have an alias for delete but not for free.

Agreed. I think alias = "delete" should also not be there.