.NET Framework Class Library
StringBuilder.Insert Method (Int32, Char[])
Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position.
Assembly: mscorlib (in mscorlib.dll)
Syntax
Visual Basic
Public Function Insert ( _ index As Integer, _ value As Char() _ ) As StringBuilder
C#
public StringBuilder Insert( int index, char[] value )
Visual C++
public: StringBuilder^ Insert( int index, array<wchar_t>^ value )
F#
member Insert : index:int * value:char[] -> StringBuilder
Parameters
- index
- Type: System.Int32
The position in this instance where insertion begins.
- value
- Type: System.Char[]
The character array to insert.
Return Value
Type: System.Text.StringBuilderA reference to this instance after the insert operation has completed.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentOutOfRangeException |
index is less than zero or greater than the length of this instance. -or- Enlarging the value of this instance would exceed MaxCapacity. |
Remarks
Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed.
If value is null, the StringBuilder is not changed.
Examples
The following example demonstrates the Insert method.
Visual Basic
Imports System Imports System.Text Class Sample ' index: 012345 Private Shared initialValue As String = "--[]--" Private Shared sb As StringBuilder Public Shared Sub Main() Dim xyz As String = "xyz" Dim abc As Char() = {"a"c, "b"c, "c"c} Dim star As Char = "*"c Dim obj As [Object] = 0 Dim xBool As Boolean = True Dim xByte As Byte = 1 Dim xInt16 As Short = 2 Dim xInt32 As Integer = 3 Dim xInt64 As Long = 4 Dim xDecimal As [Decimal] = 5 Dim xSingle As Single = 6.6F Dim xDouble As Double = 7.7 ' The following types are not CLS-compliant. ' Dim xUInt16 As System.UInt16 = 8 ' Dim xUInt32 As System.UInt32 = 9 ' Dim xUInt64 As System.UInt64 = 10 ' Dim xSByte As System.SByte = - 11 ' Console.WriteLine("StringBuilder.Insert method") sb = New StringBuilder(initialValue) sb.Insert(3, xyz, 2) Show(1, sb) sb.Insert(3, xyz) Show(2, sb) sb.Insert(3, star) Show(3, sb) sb.Insert(3, abc) Show(4, sb) sb.Insert(3, abc, 1, 2) Show(5, sb) sb.Insert(3, xBool) ' True Show(6, sb) sb.Insert(3, obj) ' 0 Show(7, sb) sb.Insert(3, xByte) ' 1 Show(8, sb) sb.Insert(3, xInt16) ' 2 Show(9, sb) sb.Insert(3, xInt32) ' 3 Show(10, sb) sb.Insert(3, xInt64) ' 4 Show(11, sb) sb.Insert(3, xDecimal) ' 5 Show(12, sb) sb.Insert(3, xSingle) ' 6.6 Show(13, sb) sb.Insert(3, xDouble) ' 7.7 Show(14, sb) ' The following Insert methods are not CLS-compliant. ' sb.Insert(3, xUInt16) ' 8 ' sb.Insert(3, xUInt32) ' 9 ' sb.Insert(3, xUInt64) ' 10 ' sb.Insert(3, xSByte) ' -11 End Sub 'Main Public Shared Sub Show(overloadNumber As Integer, sbs As StringBuilder) Console.WriteLine("{0,2:G} = {1}", overloadNumber, sbs.ToString()) sb = New StringBuilder(initialValue) End Sub 'Show End Class 'Sample ' 'This example produces the following results: ' 'StringBuilder.Insert method ' 1 = --[xyzxyz]-- ' 2 = --[xyz]-- ' 3 = --[*]-- ' 4 = --[abc]-- ' 5 = --[bc]-- ' 6 = --[True]-- ' 7 = --[0]-- ' 8 = --[1]-- ' 9 = --[2]-- '10 = --[3]-- '11 = --[4]-- '12 = --[5]-- '13 = --[6.6]-- '14 = --[7.7]-- '
C#
using System; using System.Text; class Sample { // index: 012345 static string initialValue = "--[]--"; static StringBuilder sb; public static void Main() { string xyz = "xyz"; char[] abc = {'a', 'b', 'c'}; char star = '*'; Object obj = 0; bool xBool = true; byte xByte = 1; short xInt16 = 2; int xInt32 = 3; long xInt64 = 4; Decimal xDecimal = 5; float xSingle = 6.6F; double xDouble = 7.7; // The following types are not CLS-compliant. ushort xUInt16 = 8; uint xUInt32 = 9; ulong xUInt64 = 10; sbyte xSByte = -11; // Console.WriteLine("StringBuilder.Insert method"); sb = new StringBuilder(initialValue); sb.Insert(3, xyz, 2); Show(1, sb); sb.Insert(3, xyz); Show(2, sb); sb.Insert(3, star); Show(3, sb); sb.Insert(3, abc); Show(4, sb); sb.Insert(3, abc, 1, 2); Show(5, sb); sb.Insert(3, xBool); // True Show(6, sb); sb.Insert(3, obj); // 0 Show(7, sb); sb.Insert(3, xByte); // 1 Show(8, sb); sb.Insert(3, xInt16); // 2 Show(9, sb); sb.Insert(3, xInt32); // 3 Show(10, sb); sb.Insert(3, xInt64); // 4 Show(11, sb); sb.Insert(3, xDecimal); // 5 Show(12, sb); sb.Insert(3, xSingle); // 6.6 Show(13, sb); sb.Insert(3, xDouble); // 7.7 Show(14, sb); // The following Insert methods are not CLS-compliant. sb.Insert(3, xUInt16); // 8 Show(15, sb); sb.Insert(3, xUInt32); // 9 Show(16, sb); sb.Insert(3, xUInt64); // 10 Show(17, sb); sb.Insert(3, xSByte); // -11 Show(18, sb); // } public static void Show(int overloadNumber, StringBuilder sbs) { Console.WriteLine("{0,2:G} = {1}", overloadNumber, sbs.ToString()); sb = new StringBuilder(initialValue); } } /* This example produces the following results: StringBuilder.Insert method 1 = --[xyzxyz]-- 2 = --[xyz]-- 3 = --[*]-- 4 = --[abc]-- 5 = --[bc]-- 6 = --[True]-- 7 = --[0]-- 8 = --[1]-- 9 = --[2]-- 10 = --[3]-- 11 = --[4]-- 12 = --[5]-- 13 = --[6.6]-- 14 = --[7.7]-- 15 = --[8]-- 16 = --[9]-- 17 = --[10]-- 18 = --[-11]-- */
Visual C++
using namespace System; using namespace System::Text; ref class Sample { private: // index: 012345 static String^ initialValue = "--[]--"; static StringBuilder^ sb; public: static void Main() { String^ xyz = "xyz"; array<Char>^abc = {'a','b','c'}; Char star = '*'; Object^ obj = 0; bool xBool = true; Byte xByte = 1; short xInt16 = 2; int xInt32 = 3; long xInt64 = 4; Decimal xDecimal = 5; float xSingle = 6.6F; double xDouble = 7.7; // The following types are not CLS-compliant. UInt16 xUInt16 = 8; UInt32 xUInt32 = 9; UInt64 xUInt64 = 10; SByte xSByte = -11; // Console::WriteLine( "StringBuilder.Insert method" ); sb = gcnew StringBuilder( initialValue ); sb->Insert( 3, xyz, 2 ); Show( 1, sb ); sb->Insert( 3, xyz ); Show( 2, sb ); sb->Insert( 3, star ); Show( 3, sb ); sb->Insert( 3, abc ); Show( 4, sb ); sb->Insert( 3, abc, 1, 2 ); Show( 5, sb ); sb->Insert( 3, xBool ); // True Show( 6, sb ); sb->Insert( 3, obj ); // 0 Show( 7, sb ); sb->Insert( 3, xByte ); // 1 Show( 8, sb ); sb->Insert( 3, xInt16 ); // 2 Show( 9, sb ); sb->Insert( 3, xInt32 ); // 3 Show( 10, sb ); sb->Insert( 3, xInt64 ); // 4 Show( 11, sb ); sb->Insert( 3, xDecimal ); // 5 Show( 12, sb ); sb->Insert( 3, xSingle ); // 6.6 Show( 13, sb ); sb->Insert( 3, xDouble ); // 7.7 Show( 14, sb ); // The following Insert methods are not CLS-compliant. sb->Insert( 3, xUInt16 ); // 8 Show( 15, sb ); sb->Insert( 3, xUInt32 ); // 9 Show( 16, sb ); sb->Insert( 3, xUInt64 ); // 10 Show( 17, sb ); sb->Insert( 3, xSByte ); // -11 Show( 18, sb ); // } static void Show( int overloadNumber, StringBuilder^ sbs ) { Console::WriteLine( "{0,2:G} = {1}", overloadNumber, sbs ); sb = gcnew StringBuilder( initialValue ); } }; int main() { Sample::Main(); } /* This example produces the following results: StringBuilder.Insert method 1 = --[xyzxyz]-- 2 = --[xyz]-- 3 = --[*]-- 4 = --[abc]-- 5 = --[bc]-- 6 = --[True]-- 7 = --[0]-- 8 = --[1]-- 9 = --[2]-- 10 = --[3]-- 11 = --[4]-- 12 = --[5]-- 13 = --[6.6]-- 14 = --[7.7]-- 15 = --[8]-- 16 = --[9]-- 17 = --[10]-- 18 = --[-11]-- */
Version Information
.NET Framework
Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0.NET Framework Client Profile
Supported in: 4, 3.5 SP1Portable Class Library
Supported in: Portable Class LibraryPlatforms
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
See Also