This documentation is archived and is not being maintained.

String Constructor (SByte*, Int32, Int32)

.NET Framework 1.1

Initializes a new instance of the String class to the value indicated by a specified pointer to an array of 8-bit signed integers, a starting character position within that array, and a length.

This constructor is not CLS-compliant. For more information about CLS compliance, see What is the Common Language Specification.

[C#]
[CLSCompliant(false)]
unsafe public String(
 sbyte* value,
 int startIndex,
 int length
);
[C++]
[CLSCompliant(false)]
public: String(
 char* value,
 int startIndex,
 int length
);

[Visual Basic] This constructor cannot be used in Visual Basic.

[JScript] This constructor cannot be used in JScript.

Parameters [C#, C++]

value
A pointer to an array of 8-bit signed integers.
startIndex
The starting position within value.
length
The number of characters within value to use.

Exceptions [C#, C++]

Exception Type Condition
ArgumentOutOfRangeException startIndex or length is less than zero.
ArgumentException value + startIndex is less than 64K.

-or-

A new instance of String could not be initialized using value and the current code page.

Remarks [C#, C++]

If value is a null pointer or length is zero, the new instance is initialized to the empty string ("").

This constructor copies Unicode characters from value, starting at startIndex and ending at (startIndex + length- 1).

If the specified range is outside of the memory allocated for the sequence of characters, the behavior of this constructor is system dependent. For example, such a situation might cause an access violation.

In C#, this constructor is defined only in the context of unmanaged code.

Example

[C#, C++] The following simple code example demonstrates how you can create an instance of the String class with this constructor.

[C#] 
unsafe
{
    // Null terminated ASCII characters in an sbyte array
    String szAsciiUpper = null;
    sbyte[] sbArr1 = new sbyte[] { 0x41, 0x42, 0x43, 0x00 };
    // Instruct the Garbage Collector not to move the memory
    fixed(sbyte* pAsciiUpper = sbArr1)
    {
        szAsciiUpper = new String(pAsciiUpper);
    }
    String szAsciiLower = null;
    sbyte[] sbArr2 = { 0x61, 0x62, 0x63, 0x00 };
    // Instruct the Garbage Collector not to move the memory
    fixed(sbyte* pAsciiLower = sbArr2)
    {
        szAsciiLower = new String(pAsciiLower, 0, sbArr2.Length);
    }
    // Prints "ABC abc"
    Console.WriteLine(szAsciiUpper + " " + szAsciiLower);

    // Compare Strings - the result is true
    Console.WriteLine("The Strings are equal when capitalized ? " +
        (String.Compare(szAsciiUpper.ToUpper(), szAsciiLower.ToUpper())==0?"true":"false") );

    // This is the effective equivalent of another Compare method, which ignores case
    Console.WriteLine("The Strings are equal when capitalized ? " +
        (String.Compare(szAsciiUpper, szAsciiLower, true)==0?"true":"false") );
}

[C++] 
// Null terminated ASCII characters in a simple char array
char charArray3 [4]  = { 0x41, 0x42, 0x43, 0x00 };
char* pstr3 = &charArray3[0];
String* szAsciiUpper = new String(pstr3);

char charArray4 [4]  = { 0x61, 0x62, 0x63, 0x00 };
char* pstr4 = &charArray4[0];
String* szAsciiLower = new String(pstr4, 0, sizeof(charArray4));

// Prints "ABC abc"
Console::WriteLine(String::Concat(szAsciiUpper," ", szAsciiLower));

// Compare Strings - the result is true
Console::WriteLine(String::Concat("The Strings are equal when capitalized ? ",
    (0 == String::Compare(szAsciiUpper->ToUpper(),szAsciiLower->ToUpper())?"TRUE":"FALSE") ));

// This is the effective equivalent of another Compare method, which ignores case
Console::WriteLine(String::Concat("The Strings are equal when capitalized ? ",
    (0 == String::Compare(szAsciiUpper, szAsciiLower, true)?"TRUE":"FALSE") ) );

[Visual Basic, JScript] No example is available for Visual Basic or JScript. To view a C# or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements [C#, C++]

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

See Also

String Class | String Members | System Namespace | String Constructor Overload List | SByte | Int32

Show: