SecureString::InsertAt Method (Int32, Char)

.NET Framework (current version)

Inserts a character in this secure string at the specified index position.

Namespace: System.Security
Assembly: mscorlib (in mscorlib.dll)

Syntax

public:
[HandleProcessCorruptedStateExceptionsAttribute]
void InsertAt(
	int index,
	wchar_t c
)

Parameters

index: Type: System::Int32
The index position where parameter c is inserted.

c: Type: System::Char
The character to insert.

Exceptions

Exception	Condition
ObjectDisposedException	This secure string has already been disposed.
InvalidOperationException	This secure string is read-only.
ArgumentOutOfRangeException	index is less than zero, or greater than the length of this secure string. -or- Performing this operation would make the length of this secure string greater than 65,536 characters.
CryptographicException	An error occurred while protecting or unprotecting the value of this secure string.

Remarks

The index is zero-based; the first character in this secure string is at index position zero.

If the implementation uses a protection mechanism, such as encryption, the value of the secure string, if any, is unprotected; c is inserted at the specified index position; then the new value is re-protected. The InsertAt method yields the same results as the AppendChar method, which inserts a character at the end of a secure string, if the index parameter of InsertAt is set to the length of this instance.

Examples

The following example demonstrates how the AppendChar, InsertAt, RemoveAt, SetAt, and Clear methods affect the value of a SecureString object.

C++

using namespace System;
using namespace System::Security;

void main()
{
    String^ msg = L"   The current length of the SecureString object: {0}\n";
    SecureString ^ ss = gcnew SecureString;

    Console::WriteLine(L"1) Instantiate the SecureString object:");
    Console::WriteLine(msg, ss->Length );

    Console::WriteLine(L"2) Append 'a' to the value:");
    ss->AppendChar('a');
    Console::WriteLine(msg, ss->Length );

    Console::WriteLine(L"3) Append 'X' to the value:");
    ss->AppendChar('X');
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"4) Append 'c' to the value:");
    ss->AppendChar('c');
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"5) Insert 'd' at the end of the value:");
    ss->InsertAt(ss->Length, 'd');
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"6) Remove the last character ('d') from the value:");
    ss->RemoveAt(3);
    Console::WriteLine(msg, ss->Length);

    Console::WriteLine(L"7) Set the second character ('X') of the value to 'b':" );
    ss->SetAt(1, 'b');
    Console::WriteLine(msg, ss->Length );

    Console::WriteLine(L"8) Delete the value of the SecureString object:");
    ss->Clear();
    Console::WriteLine(msg, ss->Length);

    delete ss;
}

/*
This code example produces the following results:

This example demonstrates the effect of the AppendChar, InsertAt,
RemoveAt, SetAt, and Clear methods on the value of a SecureString
object. This example simulates the value of the object because the
actual value is encrypted.

1) The initial value of the SecureString object:
   SecureString = ""
   Length = 0

2) AppendChar: Append 'a' to the value:
   SecureString = "a"
   Length = 1

3) AppendChar: Append 'X' to the value:
   SecureString = "aX"
   Length = 2

4) AppendChar: Append 'c' to the value:
   SecureString = "aXc"
   Length = 3

5) InsertAt: Insert 'd' at the end of the value (equivalent
     to AppendChar):
   SecureString = "aXcd"
   Length = 4

6) RemoveAt: Remove the last character ('d') from the value:
   SecureString = "aXc"
   Length = 3

7) SetAt: Set the second character ('X') of the value to 'b':
   SecureString = "abc"
   Length = 3

8) Clear: Delete the value of the SecureString object:
   SecureString = ""
   Length = 0
*/

Version Information

.NET Framework
Available since 2.0