From 7c84655ec35ad51e42a6d43bb06dacf195387607 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Se=C3=A1n=20de=20B=C3=BArca?= <sdeburca@fastmail.net>
Date: Fri, 7 Nov 2025 09:47:55 -0800
Subject: [PATCH] alloc: Document panics when allocations will exceed max

---
 library/alloc/src/string.rs  | 21 +++++++++++++++++----
 library/alloc/src/vec/mod.rs |  9 +++++++--
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index 31743b0e35b24..e38a67a984f87 100644
--- a/library/alloc/src/string.rs
+++ b/library/alloc/src/string.rs
@@ -461,6 +461,10 @@ impl String {
     ///
     /// [`new`]: String::new
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1094,6 +1098,10 @@ impl String {
 
     /// Appends a given string slice onto the end of this `String`.
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1116,8 +1124,9 @@ impl String {
     ///
     /// # Panics
     ///
-    /// Panics if the range has `start_bound > end_bound`, or, if the range is
-    /// bounded on either end and does not lie on a [`char`] boundary.
+    /// Panics if the range has `start_bound > end_bound`, if the range is
+    /// bounded on either end and does not lie on a [`char`] boundary, or if the
+    /// new capacity exceeds `isize::MAX` bytes.
     ///
     /// # Examples
     ///
@@ -1173,7 +1182,7 @@ impl String {
     ///
     /// # Panics
     ///
-    /// Panics if the new capacity overflows [`usize`].
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
     ///
     /// # Examples
     ///
@@ -1223,7 +1232,7 @@ impl String {
     ///
     /// # Panics
     ///
-    /// Panics if the new capacity overflows [`usize`].
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
     ///
     /// # Examples
     ///
@@ -1387,6 +1396,10 @@ impl String {
 
     /// Appends the given [`char`] to the end of this `String`.
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index dc610d7b46741..f6e650a8ac808 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -3292,6 +3292,10 @@ impl<T: Clone, A: Allocator> Vec<T, A> {
     /// except that it also works with slice elements that are Clone but not Copy.
     /// If Rust gets specialization this function may be deprecated.
     ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
+    ///
     /// # Examples
     ///
     /// ```
@@ -3313,8 +3317,9 @@ impl<T: Clone, A: Allocator> Vec<T, A> {
     ///
     /// # Panics
     ///
-    /// Panics if starting index is greater than the end index
-    /// or if the index is greater than the length of the vector.
+    /// Panics if starting index is greater than the end index, if the index is
+    /// greater than the length of the vector, or if the new capacity exceeds
+    /// `isize::MAX` _bytes_.
     ///
     /// # Examples
     ///