feat: IDLBuilder.try_reserve_value_serializer_capacity (#586)

Changelog.md

@@ -1,6 +1,10 @@
 
 # Changelog
 
+## [Unreleased]
+
+* Add `IDLBuilder.try_reserve_value_serializer_capacity()` to reserve capacity before serializing a large amount of data.
+
 ## 2024-05-03
 
 ### Candid 0.10.10

rust/candid/src/error.rs

@@ -1,6 +1,7 @@
 //! `candid::Result<T> = Result<T, candid::Error>>`
 
 use serde::{de, ser};
+use std::collections::TryReserveError;
 use std::{io, num::ParseIntError};
 use thiserror::Error;
 
@@ -17,6 +18,9 @@ pub enum Error {
     #[error("binary parser error: {}", .0.first().map_or_else(|| "io error".to_string(), |f| format!("{} at byte offset {}", f.message, f.pos/2)))]
     Binread(Vec<Label>),
 
+    #[error(transparent)]
+    Reserve(#[from] TryReserveError),
+
     #[error("Subtyping error: {0}")]
     Subtype(String),
 

rust/candid/src/ser.rs

@@ -7,7 +7,7 @@ use super::types::value::IDLValue;
 use super::types::{internal::Opcode, Field, Type, TypeEnv, TypeInner};
 use byteorder::{LittleEndian, WriteBytesExt};
 use leb128::write::{signed as sleb128_encode, unsigned as leb128_encode};
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, TryReserveError};
 use std::io;
 use std::vec::Vec;
 
@@ -71,6 +71,14 @@ impl IDLBuilder {
         self.serialize(&mut vec)?;
         Ok(vec)
     }
+    /// If serializing a large amount of data, you can try to reserve the capacity of the
+    /// value serializer ahead of time to avoid reallocation.
+    pub fn try_reserve_value_serializer_capacity(
+        &mut self,
+        additional: usize,
+    ) -> std::result::Result<(), TryReserveError> {
+        self.value_ser.try_reserve(additional)
+    }
 }
 
 /// A structure for serializing Rust values to IDL.
@@ -99,6 +107,10 @@ impl ValueSerializer {
         self.value.write_all(bytes)?;
         Ok(())
     }
+    #[doc(hidden)]
+    pub fn try_reserve(&mut self, additional: usize) -> std::result::Result<(), TryReserveError> {
+        self.value.try_reserve(additional)
+    }
 }
 
 macro_rules! serialize_num {