diff --git a/src/libraries/System.Private.CoreLib/src/System/String.cs b/src/libraries/System.Private.CoreLib/src/System/String.cs index 234f5e61529ad2..8549bf5d88035d 100644 --- a/src/libraries/System.Private.CoreLib/src/System/String.cs +++ b/src/libraries/System.Private.CoreLib/src/System/String.cs @@ -518,8 +518,25 @@ public static bool IsNullOrWhiteSpace([NotNullWhen(false)] string? value) } /// - /// Returns a reference to the first element of the String. If the string is null, an access will throw a NullReferenceException. + /// Returns a read-only reference to the first element of the String. If the string is null, an access will throw a NullReferenceException. /// + /// + /// + /// The type is immutable: the value of a object + /// cannot be changed after the object is created. The reference returned by this method is + /// ref readonly and must only be used for reading characters; writing to + /// the referenced memory is not permitted and results in undefined behavior, including + /// potential corruption of the managed heap. + /// + /// + /// When using this method (or the equivalent C++/CLI PtrToStringChars function) to + /// obtain a pinned interior pointer to the string's character data, the resulting pointer + /// must be treated as read-only. In C++/CLI, PtrToStringChars exposes the pointer + /// as const wchar_t* to reflect this constraint. Casting away const + /// and writing through the pointer will silently corrupt the CLR heap and may cause + /// crashes or incorrect behavior at an unrelated location later in program execution. + /// + /// [EditorBrowsable(EditorBrowsableState.Never)] [NonVersionable] public ref readonly char GetPinnableReference() => ref _firstChar;