Expose rb_hash_new_capa(long)

[Feature #18683]

This allows parsers and similar libraries to create Hashes of
a certain capacity in advance. It's useful when the key and values
are streamed, hence `bulk_insert()` can't be used.

Author: byroot

hash.c

@@ -1575,6 +1575,12 @@ rb_hash_new_with_size(st_index_t size)
     return ret;
 }
 
+VALUE
+rb_hash_new_capa(long capa)
+{
+    return rb_hash_new_with_size((st_index_t)capa);
+}
+
 static VALUE
 hash_copy(VALUE ret, VALUE hash)
 {

include/ruby/internal/intern/hash.h

@@ -106,6 +106,17 @@ VALUE rb_hash(VALUE obj);
  */
 VALUE rb_hash_new(void);
 
+/**
+ * Identical to rb_hash_new(), except it additionally specifies how many keys
+ * it is expected to contain. This way you can create a hash that is large enough
+ * for your need. For large hashes it means it won't need to be reallocated and
+ * rehashed as much, improving performance.
+ *
+ * @param[in]  capa  Designed capacity of the hash.
+ * @return     An empty Hash, whose capacity is `capa`.
+ */
+VALUE rb_hash_new_capa(long capa);
+
 /**
  * Duplicates a hash.
  *