ACP: hash_map! macro to create `HashMap`s such as `vec!`

[stifskere]

Proposal

Add a hash_map! macro that would possibly generate a HashMap instead of using HashMap::from([]) which doesn't feel that idiomatic.

This isn't a performance addition, and wouldn't really change anything else more than add an idiomatic way of creating HashMaps.

Problem statement

Adding this macro would allow to make code cleaner, instead of having an iterable of tuples that is then collected to a HashMap we would have a more idiomatic macro at the style of vec! and this would possibly be an addition and motivation to make this for further structures.

Motivating examples or use cases

I made a library, which has templates, to fill these there is a HashMap<K: ToString, V: ToString> parameter, creating that is quite bulky for the user. The only way for it to not be bulky is to create that step by step, but sometimes this parameter will be simply a HashMap::from instantiation.

let translations = TestContext::load_translations(
    Language::ES,
    &HashMap::from([
        ("user", "John")
    ])
)

Solution sketch

The macro would look something along the lines of

hash_map!{
  "key" => "value",
  "key" => "value"
}

and this could directly generate a call to HashMap::from such as

macro_rules! hash_map {
    ($($key:expr => $value:expr),* $(,)?) => {{
        std::collections::HashMap::from([
            $(($key, $value)),*
        ])
    }}
}

Alternatives

This is too small to be made a crate, and re-implementing the macro on every project feels bulky.

Links and related work

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[shepmaster]

See also rust-lang/rfcs#542

[stifskere]

See also rust-lang/rfcs#542

Wouldn't this be part of the libs? should I keep this issue open or close it in favor of of that RFC?

[the8472]

This is the right place, issues on the RFC repo only have limited significance.

[tgross35]

I’ve seen a collection! macro proposed before that accepts either { key: value } syntax or [item, item, item]. It expands to either an array of k-v tuples or an array of items, and then calls .collect().

The type needs to be specified which is slightly less nice, but the upside is a single macro works for everything.

let hm: HashMap<_, _> = collection! { “foo”: 10, “bar”: 123 };
let bm: BTreeMap<_, _> = collection! { “foo”: 10, “bar”: 123 };
let hs: HashSet<_> = collection! { “foo, “bar”, “baz” };

// also custom types if they implement FromIter
let mm: MyMap<_> = collection! { … };

// Some redundancy with vec!
let v: Vec<_> = collection![1, 2, 3];

[stifskere]

I’ve seen a collection! macro proposed before that accepts either { key: value } syntax or [item, item, item]. It expands to either an array of k-v tuples or an array of items, and then calls .collect().

The type needs to be specified which is slightly less nice, but the upside is a single macro works for everything.

let hm: HashMap<_, > = collection! { “foo”: 10, “bar”: 123 };
let bm: BTreeMap<, > = collection! { “foo”: 10, “bar”: 123 };
let hs: HashSet<> = collection! { “foo, “bar”, “baz” };

// also custom types if they implement FromIter
let mm: MyMap<_> = collection! { … };

// Some redundancy with vec!
let v: Vec<_> = collection![1, 2, 3];

The pros of this is that if you are passing that invocation as argument or you are using a reference to it right after the type is inferred, and no problem after that.

The cons of this may be complexity on maintaining that macro, I don't know if rust works with the single principle practice but I feel it may be to complex. Another con I find is the redundancy of it, when you read code that you have never read and you see a function invocation, sometimes you may imagine what's up if you can read the arguments, but collection! may seem ambiguous in some cases.

[shepmaster]

I’ve seen a collection! macro proposed before

See also rust-lang/rfcs#542 (comment)

[kennytm]

Add a hash_map! macro that would possibly generate a HashMap instead of using HashMap::from([]) which doesn't feel that idiomatic.

Alternative, we just confirm HashMap::{from, from_iter} are idiomatic?

[stifskere]

Add a hash_map! macro that would possibly generate a HashMap instead of using HashMap::from([]) which doesn't feel that idiomatic.

Alternative, we just confirm HashMap::{from, from_iter} are idiomatic?

It's not the from that I say is not idiomatic, it's the array of tuples that is not, In code you can just convert a HashMap to an array of Vector2 if you wanted, which is why I say it's not idiomatic.

[stifskere]

I can open a draft pull request if necessary to integrate the macro. I'd like to contribute to rust in some way.

[joshtriplett]

We discussed this at length in today's @rust-lang/libs-api meeting.

We were enthusiastic about adding a macro for this.

We talked for a while about two things:

1. The name. We talked at length about the tradeoffs between a shorter name (since this exists to be a concise/simple syntax) and a descriptive one (matching the type). @Amanieu felt that map! would be ambiguous with the verb "map", and would prefer to match the type name. We talked about hash_map!, hashmap!, and hmap!. (And, likewise for a macro for HashSet.)

2. The syntax. We talked about potentially using : instead of =>. Since expr doesn't allow : to follow it, that would require either a lang decision to change the permitted follow set of expr, or using a tt-muncher or built-in macro. However, it would match the syntax we use for HashMap's Debug output, as well as the syntax we use for struct fields.

[traviscross]

In the call, we also discussed whether this could be used for hash maps with a non-default RandomState. @dtolnay had examples of how we had supported this in macros, with fallback, in other cases.

One aspect that may be important to our decision on that, as well as to other matters such as the name of the macro, is that once we add this, people will be likely to reach for it to construct empty hash maps (instead of HashMap::new()), just as people reach for vec![] instead of Vec::new().

On the question of which token to use for separation, another choice we discussed here is =. It has the same problem as : in that it's allowed in our expression grammar, but we could still conceivably use it by writing the macro in such a way as to simply disallow unparenthesized expressions of this kind in the key. The choice of = avoids the possible conflict with type ascription, and on lang, we have discussed a certain unhappiness for having used : for struct initialization and considered whether we might, over an edition, be able to do something about it. Those discussions are still early and uncertain, but I wouldn't want us to double down on : for the syntax here without having further explored that discussion first.

cc @rust-lang/lang

[traviscross]

Another question, brought up on the call by @the8472, is whether we'd want to require a comma afterward when a block is used for a value, or whether we'd want to do what match does and allow the comma to be elided in this case.

[stifskere]

The name. We talked at length about the tradeoffs between a shorter name (since this exists to be a concise/simple syntax) and a descriptive one (matching the type). @Amanieu felt that map! would be ambiguous with the verb "map", and would prefer to match the type name. We talked about hash_map!, hashmap!, and hmap!. (And, likewise for a macro for HashSet.)

The vec! macro is called like that because the target type is a Vec, literaly translating the name from PascalCase to snake_case. It would make sense for this macro to be called hash_map! since the macro casing is snake_case.

The syntax. We talked about potentially using : instead of =>. Since expr doesn't allow : to follow it, that would require either a lang decision to change the permitted follow set of expr, or using a tt-muncher or built-in macro. However, it would match the syntax we use for HashMap's Debug output, as well as the syntax we use for struct fields.

Structs have it this way, I'd tie this to struct declaration, instantiation and so on by using the : operator. If this needs to some day change macros are flexible enough to deprecate a branch, if not this could be added in a separate feature request. Since you mention the fact that changes to the struct declaration operator might take years, I wouldn't worry about it for now.

In the call, we also discussed whether this could be used for hash maps with a non-default RandomState. @dtolnay had examples of how we had supported this in macros, with fallback, in other cases.

The vec! macro definitively does not support that If that had to be added I'd vote for merging the whole thing and adding a collection! macro of some sort, even tho ambiguous. otherwise it being added to the current macros should be discussed in another issue, I'd first implement this and then make an issue as "Allowing other states in collection macros such as vec and hash_map". Definitively not merging it with this.

One aspect that may be important to our decision on that, as well as to other matters such as the name of the macro, is that once we add this, people will be likely to reach for it to construct empty hash maps (instead of HashMap::new()), just as people reach for vec![] instead of Vec::new().

I can see that, definitively a good addition.

Another question, brought up on the call by @the8472, is whether we'd want to require a comma afterward when a block is used for a value, or whether we'd want to do what match does and allow the comma to be elided in this case.

I would allow the user to choose, particularly in cases where a procedural macro is generated or a formatter such as rustfmt or more advanced ones that support formatting macro arguments is used, since these might introduce issues.