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.

1 files changed, 11 insertions, 0 deletions

diff --git a/include/ruby/internal/intern/hash.h b/include/ruby/internal/intern/hash.h
index 3cce7f61c7..af8dfd5d8f 100644
--- a/include/ruby/internal/intern/hash.h
+++ b/include/ruby/internal/intern/hash.h
@@ -107,6 +107,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.
  *
  * @param[in]  hash  An instance of ::rb_cHash.