System.String Class

public sealed class String : ICloneable, IComparable, IEnumerable, IComparable<String>, IEquatable<String>, IEnumerable<Char>

Base Types

Object
  String

This type implements IComparable, ICloneable, System.IComparable<System.String>, System.IEquatable<System.String>, IEnumerable, and System.Collections.Generic.IEnumerable<System.Char>.

Assembly

mscorlib

Library

BCL

Summary

Represents an immutable series of characters.

Description

An index is the position of a character within a string. The first character in the string is at index 0. The length of a string is the number of characters it is made up of. The last accessible index of a string instance is System.String.Length - 1.

Strings are immutable; once created, the contents of a String do not change. Combining operations, such as System.String.Replace(System.Char,System.Char), cannot alter existing strings. Instead, such operations return a new string that contains the results of the operation, an unchanged string, or the null value. To perform modifications to a String use the StringBuilder .

Implementations of String are required to contain a variable-length character buffer positioned a fixed number of bytes after the beginning of the String object. [Note: The System.Runtime.CompilerServices.RuntimeHelpers.OffsetToStringData method returns the number of bytes between the start of the String object and the character buffer. This information is intended primarily for use by compilers, not application programmers. For additional information, see System.Runtime.CompilerServices.RuntimeHelpers.OffsetToStringData .]

[Note: Comparisons and searches are case-sensitive by default, and unless otherwise specified, use the culture defined (if any) for the current thread to determine the order of the alphabet used by the strings. This information is then used to compare the two strings on a character-by-character basis. Upper case letters evaluate greater than their lowercase equivalents.

The following characters are considered white space when present in a String instance: 0x9, 0xA, 0xB, 0xC, 0xD, 0x20, 0xA0, 0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200A, 0x200B, 0x3000, and 0xFEFF. The null character is defined as hexadecimal 0x00.

The String(String) constructor is omitted for performance reasons. If you need a copy of a String, consider using System.String.Copy(System.String) or the StringBuilder class.

To insert a formatted string representation of an object into a string, use the System.String.Format(System.String,System.Object) methods. These methods take one or more arguments to be formatted, and a format string. The format string contains literals and zero or more format specifications of the form { N [, M ][: formatSpecifier ]}, where:

• N is a zero-based integer indicating the argument to be formatted. If the actual argument is a null reference, then an empty string is used in its place.
• M is an optional integer indicating the minimum width of the region to contain the formatted value of argument N . If the length of the string representation of the value is less than M, then the region is padded with spaces. If M is negative, the formatted value is left justified in the region; if M is positive, then the value is right justified. If M is not specified, it is assumed to be zero indicating that neither padding nor alignment is customized. Note that if the length of the formatted value is greater than M, then M is ignored.
• formatSpecifier is an optional string that determines the representation used for arguments. For example, an integer can be represented in hexadecimal or decimal format, or as a monetary value. If formatSpecifier is omitted and an argument implements the IFormattable interface, then a null reference is used as the System.IFormattable.ToString(System.String,System.IFormatProvider) format specifier. Therefore, all implementations of System.IFormattable.ToString(System.String,System.IFormatProvider) are required to allow a null reference as a format specifier, and return a string containing the default representation of the object as determined by the object type. For additional information on format specifiers, see IFormattable .

If an object referenced in the format string implements IFormattable, then the System.IFormattable.ToString(System.String,System.IFormatProvider) method of the object provides the formatting. If the argument does not implement IFormattable, then the System.Object.ToString method of the object provides default formatting, and formatSpecifier , if present, is ignored. For an example that demonstrates this, see Example 2.

To include a curly bracket in a formatted string, specify the bracket twice; for example, specify "{{" to include "{" in the formatted string. See Example 1.

The Console class exposes the same functionality as the System.String.Format(System.String,System.Object) methods via System.Console.Write(System.String,System.Object) and System.Console.WriteLine. The primary difference is that the System.String.Format(System.String,System.Object) methods return the formatted string, while the System.Console methods write the formatted string to a stream.

]

When a non-empty string is searched for the first or last occurrence of an empty string, the empty string is found at the search start position.

Example

Example 1

The following example demonstrates formatting numeric data types and inserting literal curly brackets into strings.

using System;
class StringFormatTest {
    public static void Main() {
        decimal dec = 1.99999m;
        double doub = 1.0000000001;

        string somenums = String.Format("Some formatted numbers: dec={0,15:E} doub={1,20}", dec, doub);
        Console.WriteLine(somenums);

        string curlies = "Literal curly brackets: {{ and }} and {{0}}";
        Console.WriteLine(curlies);

        object nullObject = null;
        string embeddedNull = String.Format("A null argument looks like: {0}", nullObject);
        Console.WriteLine(embeddedNull);
    }
}
   

The output is

Some formatted numbers: dec=  1.999990E+000 doub=        1.0000000001
Literal curly brackets: {{ and }} and {{0}}
A null argument looks like: 
 

Example 2

The following example demonstrates how formatting works if IFormattable is or is not implemented by an argument to the System.String.Format(System.String,System.Object) method. Note that the format specifier is ignored if the argument does not implement IFormattable.

using System;
class StringFormatTest {
    public class DefaultFormatEleven {
        public override string ToString() {
            return "11 string";
        }
    }
    public class FormattableEleven:IFormattable {
        // The IFormattable ToString implementation.
        public string ToString(string format, IFormatProvider formatProvider) {
            Console.Write("[IFormattable called] ");
            return 11.ToString(format, formatProvider);
        }
        // Override Object.ToString to show that it is not called.
        public override string ToString() {
            return "Formatted 11 string";
        }
    }

    public static void Main() {
        DefaultFormatEleven def11 = new DefaultFormatEleven ();
         FormattableEleven for11 = new  FormattableEleven();
        string def11string = String.Format("{0}",def11);
        Console.WriteLine(def11string);
        // The format specifier x is ignored.
        def11string = String.Format("{0,15:x}", def11);
        Console.WriteLine(def11string);

        string form11string = String.Format("{0}",for11);
        Console.WriteLine(form11string );
        form11string = String.Format("{0,15:x}",for11);
        Console.WriteLine(form11string);
    }
}

The output is

11 string
      11 string
[IFormattable called] 11
[IFormattable called]               b
 

Example 3

The following example demonstrates searching for an empty string in a non-empty string.

using System;
class EmptyStringSearch {
	public static void Main() 	{
		Console.WriteLine("ABCDEF".IndexOf(""));
		Console.WriteLine("ABCDEF".IndexOf("", 2));
		Console.WriteLine("ABCDEF".IndexOf("", 3, 2));
		Console.WriteLine("ABCDEF".LastIndexOf(""));
		Console.WriteLine("ABCDEF".LastIndexOf("", 1));
		Console.WriteLine("ABCDEF".LastIndexOf("", 4, 2));
	}
}

The output is

0
2
3
5
1
4

Attributes

DefaultMemberAttribute("Chars")

See Also

System Namespace

Members

String Constructors

String(char, int) Constructor
String(char*) Constructor
String(char[]) Constructor
String(char*, int, int) Constructor
String(sbyte*, int, int, System.Text.Encoding) Constructor
String(char[], int, int) Constructor

String Methods

String.Clone Method
String.Compare(System.String, int, System.String, int, int, bool) Method
String.Compare(System.String, int, System.String, int, int) Method
String.Compare(System.String, System.String, bool) Method
String.Compare(System.String, System.String) Method
String.CompareOrdinal(System.String, System.String) Method
String.CompareOrdinal(System.String, int, System.String, int, int) Method
String.CompareTo(System.Object) Method
String.CompareTo(System.String) Method
String.Concat(System.Object, System.Object) Method
String.Concat(System.Object, System.Object, System.Object) Method
String.Concat(System.Object[]) Method
String.Concat(System.String, System.String) Method
String.Concat(System.String, System.String, System.String) Method
String.Concat(System.String[]) Method
String.Copy Method
String.CopyTo Method
String.EndsWith Method
String.Equals(System.Object) Method
String.Equals(System.String) Method
String.Equals(System.String, System.String) Method
String.Format(System.String, System.Object[]) Method
String.Format(System.String, System.Object) Method
String.Format(System.String, System.Object, System.Object) Method
String.Format(System.String, System.Object, System.Object, System.Object) Method
String.Format(System.IFormatProvider, System.String, System.Object[]) Method
String.GetEnumerator Method
String.GetHashCode Method
String.IndexOf(char) Method
String.IndexOf(char, int) Method
String.IndexOf(char, int, int) Method
String.IndexOf(System.String) Method
String.IndexOf(System.String, int) Method
String.IndexOf(System.String, int, int) Method
String.IndexOfAny(char[]) Method
String.IndexOfAny(char[], int) Method
String.IndexOfAny(char[], int, int) Method
String.Insert Method
String.Intern Method
String.IsInterned Method
String.Join(System.String, System.String[]) Method
String.Join(System.String, System.String[], int, int) Method
String.LastIndexOf(System.String, int) Method
String.LastIndexOf(System.String, int, int) Method
String.LastIndexOf(System.String) Method
String.LastIndexOf(char, int, int) Method
String.LastIndexOf(char, int) Method
String.LastIndexOf(char) Method
String.LastIndexOfAny(char[]) Method
String.LastIndexOfAny(char[], int) Method
String.LastIndexOfAny(char[], int, int) Method
String.PadLeft(int) Method
String.PadLeft(int, char) Method
String.PadRight(int, char) Method
String.PadRight(int) Method
String.Remove Method
String.Replace(System.String, System.String) Method
String.Replace(char, char) Method
String.Split(char[]) Method
String.Split(char[], int) Method
String.StartsWith Method
String.Substring(int, int) Method
String.Substring(int) Method
String.System.Collections.Generic.IEnumerable<System.Char>.GetEnumerator Method
String.System.Collections.IEnumerable.GetEnumerator Method
String.ToCharArray() Method
String.ToCharArray(int, int) Method
String.ToLower Method
String.ToString() Method
String.ToString(System.IFormatProvider) Method
String.ToUpper Method
String.Trim(char[]) Method
String.Trim() Method
String.TrimEnd Method
String.TrimStart Method
String.op_Equality Method
String.op_Inequality Method

String Fields

String.Empty Field

String Properties

String.Chars Property
String.Length Property

Constructs and initializes a new instance of String .

Parameters

c

A Char .

count

A Int32 containing the number of occurrences of c.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	count is less than zero.

Description

If the specified number is 0, System.String.Empty is created.

Example

The following example demonstrates using this constructor.

using System;

public class StringExample {
 public static void Main() {
 
 string s = new String('a', 10);

 Console.WriteLine(s);            
 }
}
   

The output is

aaaaaaaaaa

See Also

System.String Class, System Namespace

Constructs and initializes a new instance of String using a specified pointer to a sequence of Unicode characters.

Parameters

value

A pointer to a null-terminated array of Unicode characters. If value is a null pointer, System.String.Empty is created.

Description

This member is not CLS-compliant. For a CLS-compliant alternative, use the String(Char[] ) constructor.

This constructor copies the sequence of Unicode characters at the specified pointer until a null character (hexadecimal 0x00) is reached.

If the specified array is not null-terminated, the behavior of this constructor is system dependent. For example, such a situation might cause an access violation.

[Note: In C# this constructor is defined only in the context of unmanaged code.]

Attributes

CLSCompliantAttribute(false)

See Also

System.String Class, System Namespace

Constructs and initializes a new instance of String by copying the specified array of Unicode characters.

Parameters

value

An array of Unicode characters.

Description

If the specified array is a null reference or contains no elements, System.String.Empty is created.

See Also

System.String Class, System Namespace

Constructs and initializes a new instance of String using a specified pointer to a sequence of Unicode characters, the index within that sequence at which to start copying characters, and the number of characters to be copied to construct the String .

Parameters

value

A pointer to an array of Unicode characters.

startIndex

A Int32 containing the index within the array referenced by value from which to start copying.

length

A Int32 containing the number of characters to copy from value to the new String. If length is zero, System.String.Empty is created.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex or length is less than zero. -or- value is a null pointer and length is not zero.

Description

This member is not CLS-compliant. For a CLS-compliant alternative, use the String(Char, Int32, Int32) constructor.

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.

[Note: In C# this constructor is defined only in the context of unmanaged code.]

Attributes

CLSCompliantAttribute(false)

See Also

System.String Class, System Namespace

value

A pointer to a SByte array.

startIndex

A Int32 containing the starting position within value.

length

A Int32 containing the number of characters within value to use. If length is zero, System.String.Empty is created.

enc

A Encoding object that specifies how the array referenced by value is encoded.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex or length is less than zero. -or- value is a null pointer and length is not zero.

Description

If value is a null pointer, a System.String.Empty instance is constructed.

Attributes

CLSCompliantAttribute(false)

Library

RuntimeInfrastructure

See Also

System.String Class, System Namespace

Constructs and initializes a new instance of String using an array of Unicode characters, the index within array at which to start copying characters, and the number of characters to be copied.

Parameters

value

An array of Unicode characters.

startIndex

A Int32 containing the index within the array referenced by value from which to start copying.

length

A Int32 containing the number of characters to copy from the value array. If length is zero, System.String.Empty is created.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex or length is less than zero. -or- The sum of startIndex and length is greater than the number of elements in value .

Description

This constructor copies the sequence Unicode characters found at value between indexes startIndex and startIndex + length - 1.

See Also

System.String Class, System Namespace

Returns a reference to the current instance of String.

Return Value

A reference to the current instance of String.

Description

[Note: System.String.Clone does not generate a new String instance. Use the System.String.Copy(System.String) or System.String.CopyTo(System.Int32,System.Char[],System.Int32,System.Int32) method to create a separate String object with the same value as the current instance.

This method is implemented to support the ICloneable interface.

]

See Also

System.String Class, System Namespace

strA

The first String containing a substring to compare. Can be a null reference.

indexA

A Int32 containing the starting index of the substring within strA.

strB

The second String containing a substring to compare. Can be a null reference.

indexB

A Int32 containing the starting index of the substring within strB.

length

A Int32 containing the maximum number of characters in the substrings to compare. If length is zero, then zero is returned.

ignoreCase

A Boolean indicating if the comparison is case-insensitive. If ignoreCase is true , the comparison is case-insensitive. If ignoreCase is false , the comparison is case-sensitive, and uppercase letters evaluate greater than their lowercase equivalents.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the specified substrings. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value Type	Condition
A negative number	The substring in strA is < the substring in strB.
Zero	The substring in strA == the substring in strB, or length is zero.
A positive number	The substring in strA is > the substring in strB.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	indexA is greater than strA .Length -or- indexB is greater than strB .Length -or- indexA, indexB, or length is negative.

Description

[Note: The result of comparing any String (including the empty string) to a null reference is greater than zero. The result of comparing two null references is zero. Uppercase letters evaluate greater than their lower case equivalents.

The maximum number of characters compared is the lesser of the length of strA less indexA, the length of strB less indexB, and length.

When a culture is available, the method uses the culture of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

]

Example

The following example demonstrates comparing substrings with and without case sensitivity.

using System;
public class StringCompareExample {
 public static void Main() {
 string strA = "STRING A";
 string strB = "string b";
 int first = String.Compare( strA, strB, true );
 int second = String.Compare( strA, 0, strB, 0, 4, true );
 int third = String.Compare( strA, 0, strB, 0, 4, false );
 Console.WriteLine( "When the string 'STRING A' is compared to the string 'string b' in a case-insensitive manner, the return value is {0}.", first );
 Console.WriteLine( "When the substring 'STRI' of 'STRING A' is compared to the substring 'stri' of 'string b' in a case-insensitive manner, the return value is {0}.", second );
 Console.WriteLine( "When the substring 'STRI' of 'STRING A' is compared to the substring 'stri' of 'string b' in a case-sensitive manner, the return value is {0}.", third );
 }
}
   

The output is

When the string 'STRING A' is compared to the string 'string b' in a case-insensitive manner, the return value is -1.

When the substring 'STRI' of 'STRING A' is compared to the substring 'stri' of 'string b' in a case-insensitive manner, the return value is 0.

When the substring 'STRI' of 'STRING A' is compared to the substring 'stri' of 'string b' in a case-sensitive manner, the return value is 1.

See Also

System.String Class, System Namespace

strA

The first String to compare. Can be a null reference.

indexA

A Int32 containing the starting index of the substring within strA.

strB

The second String to compare. Can be a null reference.

indexB

A Int32 containing the starting index of the substring within strB.

length

A Int32 containing the maximum number of characters in the substrings to compare. If length is zero, then zero is returned.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the specified substrings. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value	Meaning
A negative number	The substring in strA is < the substring in strB.
Zero	The substring in strA == the substring in strB, or length is zero.
A positive number	The substring in strA is > the substring in strB.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The sum of indexA and length is greater than strA .Length . -or- The sum of indexB and length is greater than strB .Length . -or- indexA, indexB, or length is negative.

Description

[Note: The result of comparing any String (including the empty string) to a null reference is greater than zero. The result of comparing two null references is zero. Uppercase letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

]

Example

The following example demonstrates comparing substrings.

using System;
public class StringCompareExample {
 public static void Main() {
 string strA = "A string";
 string strB = "B ring";
 int first = String.Compare( strA, 4, strB, 2, 3 );
 int second = String.Compare( strA, 3, strB, 3, 3 );
 Console.WriteLine( "When the substring 'rin' of 'A string' is compared to the substring 'rin' of 'B ring', the return value is {0}.", first );
 Console.WriteLine( "When the substring 'tri' of 'A string' is compared to the substring 'ing' of 'B ring', the return value is {0}.", second );
 }
}
   

The output is

When the substring 'rin' of 'A string' is compared to the substring 'rin' of 'B ring', the return value is 0.

When the substring 'tri' of 'A string' is compared to the substring 'ing' of 'B ring', the return value is 1.

See Also

System.String Class, System Namespace

Returns sort order of two String objects, ignoring or honoring their case.

Parameters

strA

The first String to compare. Can be a null reference.

strB

The second String to compare. Can be a null reference.

ignoreCase

A Boolean indicating whether the comparison is case-insensitive. If ignoreCase is true , the comparison is case-insensitive. If ignoreCase is false , the comparison is case-sensitive, and uppercase letters evaluate greater than their lowercase equivalents.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the specified substrings. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value	Meaning
A negative number	strA is < strB.
Zero	strA == strB.
A positive number	strA is > strB.

Description

[Note: The result of comparing any String (including the empty string) to a null reference is greater than zero. The result of comparing two null references is zero. Uppercase letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

String.Compare (strA, strB, false ) is equivalent to String.Compare (strA, strB ).

]

Example

The following example demonstrates comparing strings with and without case sensitivity.

using System;
public class StringCompareExample {
 public static void Main() {
 string strA = "A STRING";
 string strB = "a string";
 int first = String.Compare( strA, strB, true );
 int second = String.Compare( strA, strB, false );
 Console.WriteLine( "When 'A STRING' is compared to 'a string' in a case-insensitive manner, the return value is {0}.", first );
 Console.WriteLine( "When 'A STRING' is compared to 'a string' in a case-sensitive manner, the return value is {0}.", second );
 }
}
   

The output is

When 'A STRING' is compared to 'a string' in a case-insensitive manner, the return value is 0.

When 'A STRING' is compared to 'a string' in a case-sensitive manner, the return value is 1.

See Also

System.String Class, System Namespace

Compares two String objects in a case-sensitive manner.

Parameters

strA

The first String to compare. Can be a null reference.

strB

The second String to compare. Can be a null reference.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the specified strings. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value	Meaning
A negative number	strA is lexicographically < strB.
Zero	strA is lexicographically == strB.
A positive number	strA is lexicographically > strB.

Description

This method performs a case-sensitive operation.

[Note: The result of comparing any String (including the empty string) to a null reference is greater than zero. The result of comparing two null references is zero. Uppercase letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

]

See Also

System.String Class, System Namespace

Compares two specified String objects based on the code points of the contained Unicode characters.

Parameters

strA

The first String to compare.

strB

The second String to compare.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the specified strings. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value	Description
A negative number	strA is < strB, or strA is a null reference.
Zero	strA == strB, or both strA and strB are null references.
A positive number	strA is > strB, or strB is a null reference.

Description

[Note: The result of comparing any String (including the empty string) to a null reference is greater than zero. The result of comparing two null references is zero. Uppercase letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

]

See Also

System.String Class, System Namespace

Compares substrings of two specified String objects based on the code points of the contained Unicode characters.

Parameters

strA

The first String to compare.

indexA

A Int32 containing the starting index of the substring in strA.

strB

The second String to compare.

indexB

A Int32 containing the starting index of the substring in strB.

length

A Int32 containing the number of characters in the substrings to compare.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the specified strings. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value Type	Condition
A negative number	The substring in strA is < the substring in strB, or strA is a null reference.
Zero	The substring in strA == the substring in strB, or both strA and strB are null references.
A positive number	The substring in strA is > the substring in strB, or strB is a null reference.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	indexA is greater than strA .Length -or- indexB is greater than strB .Length -or- indexA, indexB, or lengthis negative.

Description

When either of the String arguments is the null reference an ArgumentOutOfRangeException shall be thrown if the corresponding index is non-zero.

[Note: The maximum number of characters compared is the lesser of the length of strA less indexA, the length of strB less indexB, and length.

The result of comparing any String (including the empty string) to a null reference is greater than zero. The result of comparing two null references is zero. Upper case letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

]

See Also

System.String Class, System Namespace

value

The Object to compare to the current instance.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the current instance as compared to value. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value	Condition
A negative number	The current instance is lexicographically < value.
Zero	The current instance is lexicographically == value.
A positive number	The current instance is lexicographically > value, or value is a null reference.

Exceptions

Exception Type	Condition
ArgumentException	value is not a String.

Description

value is required to be a String object.

[Note: The result of comparing any String (including the empty string) to a null reference is greater than zero. Uppercase letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

This method is implemented to support the IComparable interface.

]

See Also

System.String Class, System Namespace

strB

The String to compare to the current instance.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the current instance as compared to strB. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Value	Condition
A negative number	The current instance is lexicographically < strB.
Zero	The current instance is lexicographically == strB.
A positive number	The current instance is lexicographically > strB, or strB is a null reference.

Description

[Note: Uppercase letters evaluate greater than their lowercase equivalents.

The method uses the culture (if any) of the current thread to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

This method is implemented to support the System.IComparable<System.String> interface.

]

See Also

System.String Class, System Namespace

Concatenates the String representations of two specified objects.

Parameters

arg0

The first Object to concatenate.

arg1

The second Object to concatenate.

Return Value

The concatenated String representation of the values of arg0 and arg1.

Description

System.String.Empty is used in place of any null argument.

This version of System.String.Concat(System.Object) is equivalent to System.String.Concat(System.Object)( arg0.ToString(), arg1.ToString () ).

[Note: If either of the arguments is an array reference, the method concatenates a string representing that array, instead of its members (for example, String )[].]

Example

The following example demonstrates concatenating two objects.

using System;
public class StringConcatExample {
 public static void Main() {
 string str = String.Concat( 'c', 32 );
 Console.WriteLine( "The concatenated Objects are: {0}", str );
 }
}
   

The output is

The concatenated Objects are: c32

See Also

System.String Class, System Namespace

Concatenates the String representations of three specified objects, in order provided.

Parameters

arg0

The first Object to concatenate.

arg1

The second Object to concatenate.

arg2

The third Object to concatenate.

Return Value

The concatenated String representations of the values of arg0, arg1, and arg2.

Description

This method concatenates the values returned by the System.String.ToString methods on every argument. System.String.Empty is used in place of any null argument.

This version of System.String.Concat(System.Object) is equivalent to String.Concat ( arg0.ToString (), arg1.ToString (), arg2.ToString () ).

Example

The following example demonstrates concatenating three objects.

using System;
public class StringConcatExample {
 public static void Main() {
 string str = String.Concat( 'c', 32, "String" );
 Console.WriteLine( "The concatenated Objects are: {0}", str );
 }
}
   

The output is

The concatenated Objects are: c32String

See Also

System.String Class, System Namespace

Concatenates the String representations of the elements in an array of Object instances.

Parameters

args

An array of Object instances to concatenate.

Return Value

The concatenated String representations of the values of the elements in args.

Exceptions

Exception Type	Condition
ArgumentNullException	args is a null reference.

Description

This method concatenates the values returned by the System.String.ToString methods on every object in the args array. System.String.Empty is used in place of any null reference in the array.

Example

The following example demonstrates concatenating an array of objects.

using System;
public class StringConcatExample {
 public static void Main() {
 string str = String.Concat( 'c', 32, "String" );
 Console.WriteLine( "The concatenated Object array is: {0}", str );
 }
}
   

The output is

The concatenated Object array is: c32String

See Also

System.String Class, System Namespace

Concatenates two specified instances of String.

Parameters

str0

The first String to concatenate.

str1

The second String to concatenate.

Return Value

A String containing the concatenation of str0 and str1.

Description

System.String.Empty is used in place of any null argument.

Example

The following example demonstrates concatenating two strings.

using System;
public class StringConcatExample {
 public static void Main() {
 string str = String.Concat( "one", "two" );
 Console.WriteLine( "The concatenated strings are: {0}", str );
 }
}
   

The output is

The concatenated strings are: onetwo

See Also

System.String Class, System Namespace

Concatenates three specified instances of String.

Parameters

str0

The first String to concatenate.

str1

The second String to concatenate.

str2

The third String to concatenate.

Return Value

A String containing the concatenation of str0, str1, and str2.

Description

System.String.Empty is used in place of any null argument.

Example

The following example demonstrates concatenating three strings.

using System;
public class StringConcatExample {
 public static void Main() {
 string str = String.Concat( "one", "two", "three" );
 Console.WriteLine( "The concatenated strings are: {0}", str );
 }
}
   

The output is

The concatenated strings are: onetwothree

See Also

System.String Class, System Namespace

values

An array of String instances to concatenate.

Return Value

A String containing the concatenated elements of values.

Exceptions

Exception Type	Condition
ArgumentNullException	values is a null reference.

Description

System.String.Empty is used in place of any null reference in the array.

Example

The following example demonstrates concatenating an array of strings.

using System;
public class StringConcatExample {
 public static void Main() {
 string str = String.Concat( "one", "two", "three", "four", "five" );
 Console.WriteLine( "The concatenated String array is: {0}", str );
 }
}
   

The output is

The concatenated String array is: onetwothreefourfive

See Also

System.String Class, System Namespace

Creates a new instance of String with the same value as a specified instance of String.

Parameters

str

The String to be copied.

Return Value

A new String with the same value as str.

Exceptions

Exception Type	Condition
ArgumentNullException	str is a null reference.

Example

The following example demonstrates copying strings.

using System;
public class StringCopyExample {
 public static void Main() {
 string strA = "string";
 Console.WriteLine( "The initial string, strA, is '{0}'.", strA );
 string strB = String.Copy( strA );
 strA = strA.ToUpper();
 Console.WriteLine( "The copied string, strB, before strA.ToUpper, is '{0}'.", strB );
 Console.WriteLine( "The initial string after StringCopy and ToUpper, is '{0}'.", strA );
 Console.WriteLine( "The copied string, strB, after strA.ToUpper, is '{0}'.", strB );
 }
}
   

The output is

The initial string, strA, is 'string'.

The copied string, strB, before strA.ToUpper, is 'string'.

The initial string after StringCopy and ToUpper, is 'STRING'.

The copied string, strB, after strA.ToUpper, is 'string'.

See Also

System.String Class, System Namespace

Copies a specified number of characters from a specified position in the current String instance to a specified position in a specified array of Unicode characters.

Parameters

sourceIndex

A Int32 containing the index of the current instance from which to copy.

destination

An array of Unicode characters.

destinationIndex

A Int32 containing the index of an array element in destination to copy.

count

A Int32 containing the number of characters in the current instance to copy to destination.

Exceptions

Exception Type	Condition
ArgumentNullException	destination is a null reference.
ArgumentOutOfRangeException	sourceIndex, destinationIndex, or count is negative -or- count is greater than the length of the substring from startIndex to the end of the current instance -or- count is greater than the length of the subarray from destinationIndex to the end of destination

Example

The following example demonstrates copying characters from a string to a Unicode character array.

using System;
public class StringCopyToExample {
 public static void Main() {
 string str = "this is the new string";
 Char[] cAry = {'t','h','e',' ','o','l','d'};
 Console.WriteLine( "The initial string is '{0}'", str );
 Console.Write( "The initial character array is: '" );
 foreach( Char c in cAry)
 Console.Write( c );
 Console.WriteLine( "'" );
 str.CopyTo( 12, cAry, 4, 3 );
 Console.Write( "The character array after CopyTo is: '" );
 foreach( Char c in cAry)
 Console.Write( c );
 Console.WriteLine("'");
 }
}
   

The output is

The initial string is 'this is the new string'

The initial character array is: 'the old'

The character array after CopyTo is: 'the new'

See Also

System.String Class, System Namespace

Returns a Boolean value that indicates whether the ending characters of the current instance match the specified String.

Parameters

value

A String to match.

Return Value

true if the end of the current instance is equal to value; false if value is not equal to the end of the current instance or is longer than the current instance.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.

Description

This method compares value with the substring at the end of the current instance that has a same length as value.

The comparison is case-sensitive.

Example

The following example demonstrates determining whether the current instance ends with a specified string.

using System;
public class StringEndsWithExample {
 public static void Main() {
 string str = "One string to compare";
 Console.WriteLine( "The given string is '{0}'", str );
 Console.Write( "The given string ends with 'compare'? " );
 Console.WriteLine( str.EndsWith( "compare" ) );
 Console.Write( "The given string ends with 'Compare'? " );
 Console.WriteLine( str.EndsWith( "Compare" ) );
 }
}
   

The output is

The given string is 'One string to compare'

The given string ends with 'compare'? True

The given string ends with 'Compare'? False

See Also

System.String Class, System Namespace

obj

A Object.

Return Value

true if obj is a String and its value is the same as the value of the current instance; otherwise, false .

Exceptions

Exception Type	Condition
NullReferenceException	The current instance is a null reference.

Description

This method checks for value equality. This comparison is case-sensitive.

[Note: This method overrides System.Object.Equals(System.Object) .]

Example

The following example demonstrates checking to see if an object is equal to the current instance.

using System;
public class StringEqualsExample {
 public static void Main() {
 string str = "A string";
 Console.WriteLine( "The given string is '{0}'", str );
 Console.Write( "The given string is equal to 'A string'? " );
 Console.WriteLine( str.Equals( "A string" ) );
 Console.Write( "The given string is equal to 'A String'? " );
 Console.WriteLine( str.Equals( "A String" ) );
 }
}
   

The output is

The given string is 'A string'

The given string is equal to 'A string'? True

The given string is equal to 'A String'? False

See Also

System.String Class, System Namespace

value

A String.

Return Value

true if the value of value is the same as the value of the current instance; otherwise, false .

Description

This method checks for value equality. This comparison is case-sensitive.

[Note: This method is implemented to support the System.IEquatable<System.String> interface.]

See Also

System.String Class, System Namespace

Determines whether two specified String objects have the same value.

Parameters

a

A String or a null reference.

b

A String or a null reference.

Return Value

true if the value of a is the same as the value of b; otherwise, false .

Description

The comparison is case-sensitive.

Example

The following example demonstrates checking to see if two strings are equal.

using System;
public class StringEqualsExample {
 public static void Main() {
 string strA = "A string";
 string strB = "a string";
 string strC = "a string";
 Console.Write( "The string '{0}' is equal to the string '{1}'? ", strA, strB );
 Console.WriteLine( String.Equals( strA, strB ) );
 Console.Write( "The string '{0}' is equal to the string '{1}'? ", strC, strB );
 Console.WriteLine( String.Equals( strC, strB ) );
 }
}
   

The output is

The string 'A string' is equal to the string 'a string'? False

The string 'a string' is equal to the string 'a string'? True

See Also

System.String Class, System Namespace

Replaces the format specification in a specified String with the textual equivalent of the value of a corresponding Object instance in a specified array.

Parameters

format

A String containing zero or more format specifications.

args

A Object array containing the objects to be formatted.

Return Value

A String containing a copy of format in which the format specifications have been replaced by the String equivalent of the corresponding instances of Object in args.

Exceptions

Exception Type	Condition
ArgumentNullException	format or args is a null reference.
FormatException	format is invalid. -or- The number indicating an argument to be formatted is less than zero, or greater than or equal to the length of the args array.

Description

If an object referenced in the format string is a null reference, an empty string is used in its place.

[Note: This version of System.String.Format(System.String,System.Object) is equivalent to System.String.Format(System.String,System.Object)( null, format, args ). For more information on the format specification see the String class overview.]

Example

The following example demonstrates the System.String.Format(System.String,System.Object) method.

using System;
public class StringFormat {
   public static void Main() {
      Console.WriteLine( String.Format("The winning numbers were {0:000} {1:000} {2:000} {3:000} {4:000} today.", 5, 10, 11, 37, 42) );
      Console.WriteLine( "The winning numbers were {0, -6}{1, -6}{2, -6}{3, -6}{4, -6} today.", 5, 10, 11, 37, 42 );
 }
}

The output is

The winning numbers were 005 010 011 037 042 today.
The winning numbers were 5     10    11    37    42     today.

See Also

System.String Class, System Namespace

Replaces the format specification in a provided String with a specified textual equivalent of the value of a specified Object instance.

Parameters

format

A String containing zero or more format specifications.

arg0

A Object to be formatted. Can be a null reference.

Return Value

A copy of format in which the first format specification has been replaced by the formatted String equivalent of the arg0.

Exceptions

Exception Type	Condition
ArgumentNullException	format is a null reference.
FormatException	The format specification in format is invalid. -or- The number indicating an argument to be formatted is less than zero, or greater than or equal to the number of provided objects to be formatted (1).

Description

If an object referenced in the format string is a null reference, an empty string is used in its place.

[Note: This version of System.String.Format(System.String,System.Object) is equivalent to String.Format ( null , format, new Object [] {arg0} ). For more information on the format specification see the String class overview.]

Example

The following example demonstrates the System.String.Format(System.String,System.Object) method.

using System;
public class StringFormat {
 public static void Main() {
 Console.WriteLine(String.Format("The high temperature today was {0:###} degrees.", 88));
 Console.WriteLine("The museum had {0,-6} visitors today.", 88);
 }
}

The output is

The high temperature today was 88 degrees.
The museum had 88     visitors today.

See Also

System.String Class, System Namespace

Replaces the format specification in a specified String with the textual equivalent of the value of two specified Object instances.

Parameters

format

A String containing zero or more format specifications.

arg0

A Object to be formatted. Can be a null reference.

arg1

A Object to be formatted. Can be a null reference.

Return Value

A String containing a copy of format in which the format specifications have been replaced by the String equivalent of arg0 and arg1.

Exceptions

Exception Type	Condition
ArgumentNullException	format is a null reference.
FormatException	format is invalid. -or- The number indicating an argument to be formatted is less than zero, or greater than or equal to the number of provided objects to be formatted (2).

Description

If an object referenced in the format string is a null reference, an empty string is used in its place.

[Note: This version of System.String.Format(System.String,System.Object) is equivalent to String.Format ( null , format, new Object[] {arg0, arg1} ). For more information on the format specification see the String class overview.]

Example

The following example demonstrates the System.String.Format(System.String,System.Object) method.

using System;
public class StringFormat {
  public static void Main() {
  Console.WriteLine( String.Format("The temperature today oscillated between {0:####} and {1:####} degrees.", 78, 100) );
  Console.WriteLine( String.Format("The temperature today oscillated between {0:0000} and {1:0000} degrees.", 78, 100) );
  Console.WriteLine( "The temperature today oscillated between {0, -4} and {1, -4} degrees.", 78, 100 );
   }
}

The output is

The temperature today oscillated between 78 and 100 degrees.
The temperature today oscillated between 0078 and 0100 degrees.
The temperature today oscillated between 78   and 100  degrees.

See Also

System.String Class, System Namespace

Replaces the format specification in a specified String with the textual equivalent of the value of three specified Object instances.

Parameters

format

A String containing zero or more format specifications.

arg0

The first Object to be formatted. Can be a null reference.

arg1

The second Object to be formatted. Can be a null reference.

arg2

The third Object to be formatted. Can be a null reference.

Return Value

A String containing a copy of format in which the first, second, and third format specifications have been replaced by the String equivalent of arg0, arg1, and arg2.

Exceptions

Exception Type	Condition
ArgumentNullException	format is a null reference.
FormatException	format is invalid. -or- The number indicating an argument to be formatted is less than zero, or greater than or equal to the number of provided objects to be formatted (3).

Description

If an object referenced in the format string is a null reference, an empty string is used in its place.

[Note: This version of System.String.Format(System.String,System.Object) is equivalent to String.Format ( null , format, new Object[] {arg0, arg1, arg2} ). For more information on the format specification see the String class overview.]

Example

The following example demonstrates the System.String.Format(System.String,System.Object) method.

using System;
public class StringFormat {
   public static void Main() {
      Console.WriteLine(String.Format("The temperature today oscillated between {0:###} and {1:###} degrees. The average temperature  was {2:000} degrees.", 78, 100, 91));
      Console.WriteLine("The temperature today oscillated between {0, 4} and {1, 4} degrees. The average temperature was {2, 4}  degrees.", 78, 100, 91);
   }
}

The output is

The temperature today oscillated between 78 and 100 degrees. The average temperature was 091 degrees.
The temperature today oscillated between   78 and  100 degrees. The average temperature was   91 degrees.

See Also

System.String Class, System Namespace

Replaces the format specification in a specified String with the culture-specific textual equivalent of the value of a corresponding Object instance in a specified array.

Parameters

provider

A IFormatProvider interface that supplies an object that provides culture-specific formatting information. Can be a null reference.

format

A String containing zero or more format specifications.

args

A Object array to be formatted.

Return Value

A String containing a copy of format in which the format specifications have been replaced by the String equivalent of the corresponding instances of Object in args .

Exceptions

Exception Type	Condition
ArgumentNullException	format or args is a null reference.
FormatException	format is invalid. -or- The number indicating an argument to be formatted (N) is less than zero, or greater than or equal to the length of the args array.

Description

If an object referenced in the format string is a null reference, an empty string is used in its place.

The format parameter string is embedded with zero or more format specifications of the form, {N [, M ][: formatString ]}, where N is a zero-based integer indicating the argument to be formatted, M is an optional integer indicating the width of the region to contain the formatted value, and formatString is an optional string of formatting codes. [Note: For more information on the format specification see the String class overview.]

See Also

System.String Class, System Namespace

A CharEnumerator object.

Description

This method is required by programming languages that support the IEnumerator interface to iterate through members of a collection.

See Also

System.String Class, System Namespace

A Int32 containing the hash code for this instance.

Description

The algorithm used to generate the hash code is unspecified.

[Note: This method overrides System.Object.GetHashCode.]

See Also

System.String Class, System Namespace

A Int32 containing the zero-based index of the first occurrence of value character in the current instance; otherwise, -1 if value was not found.

Description

This method is case-sensitive.

See Also

System.String Class, System Namespace

value

A Unicode character.

startIndex

A Int32 containing the index of the current instance from which to start searching.

Return Value

A Int32 containing the zero-based index of the first occurrence of value in the current instance starting from the specified index; otherwise, -1 if value was not found.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex is less than zero or greater than the length of the current instance.

Description

This method is case-sensitive.

Example

The following example demonstrates the System.String.IndexOf(System.Char) method.

using System;
public class StringIndexOf {
 public static void Main() {
 String str = "This is the string";
 Console.WriteLine( "Searching for the index of 'h' starting from index 0 yields {0}.", str.IndexOf( 'h', 0 ) );
 Console.WriteLine( "Searching for the index of 'h' starting from index 10 yields {0}.", str.IndexOf( 'h', 10 ) );
 }
}

The output is

Searching for the index of 'h' starting from index 0 yields 1.

Searching for the index of 'h' starting from index 10 yields -1.

See Also

System.String Class, System Namespace

value

A Unicode character.

startIndex

A Int32 containing the index of the current instance from which to start searching.

count

A Int32 containing the number of consecutive elements of the current instance to be searched starting at startIndex.

Return Value

A Int32 containing the zero-based index of the first occurrence of value in the current instance in the specified range of indexes; otherwise, -1 if value was not found.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex or count is negative -or- startIndex + count is greater than the length of the current instance.

Description

The search begins at startIndex and continues until startIndex + count - 1 is reached. The character at startIndex + count is not included in the search.

This method is case-sensitive.

See Also

System.String Class, System Namespace

Returns the index of the first occurrence of a specified String in the current instance.

Parameters

value

The String for which to search.

Return Value

A Int32 that indicates the result of the search for value in the current instance as follows:

Return Value	Description
A zero-based number equal to the index of the start of the first substring in the current instance that is equal to value .	value was found starting at the index returned.
-1	value was not found.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.

Description

The search begins at the first character of the current instance. The search is case-sensitive, culture-sensitive, and the culture (if any) of the current thread is used.

Example

The following example demonstrates the System.String.IndexOf(System.Char) method.

using System;
public class StringIndexOf {
 public static void Main() {
 String str = "This is the string";
 Console.WriteLine( "Searching for the index of \"is\" yields {0,2}.", str.IndexOf( "is" ) );
 Console.WriteLine( "Searching for the index of \"Is\" yields {0,2}.", str.IndexOf( "Is" ) );
 Console.WriteLine( "Searching for the index of \"\" yields {0,2}.", str.IndexOf( "" ) );
 }
}

The output is

Searching for the index of "is" yields 2.

Searching for the index of "Is" yields -1.

Searching for the index of "" yields 0.

See Also

System.String Class, System Namespace

Returns the index of the first occurrence of a specified String in the current instance, with the search starting from a specified index.

Parameters

value

The String for which to search.

startIndex

A Int32 containing the index of the current instance from which to start searching.

Return Value

A Int32 that indicates the result of the search for value in the current instance as follows:

Return Value	Description
A zero-based number equal to the index of the start of the first substring in the current instance that is equal to value .	value was found starting at the index returned.
-1	value was not found.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex is greater than the length of the current instance.

Description

This method is case-sensitive.

See Also

System.String Class, System Namespace

Returns the index of the first occurrence of a specified String in the current instance, with the search over the specified range starting at the provided index.

Parameters

value

The String for which to search

startIndex

A Int32 containing the index of the current instance from which to start searching.

count

A Int32 containing the number of consecutive elements of the current instance to be searched starting at startIndex.

Return Value

A Int32 that indicates the result of the search for value in the current instance as follows:

Return Value	Description
A zero-based number equal to the index of the start of the first substring in the current instance that is equal to value .	value was found starting at the index returned.
-1	value was not found.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex or count is negative -or- startIndex + count is greater than the length of the current instance.

Description

The search begins at startIndex and continues until startIndex + count - 1 is reached. The character at startIndex + count is not included in the search.

This method is case-sensitive.

See Also

System.String Class, System Namespace

System.String Class, System Namespace

anyOf

An array of Unicode characters.

startIndex

A Int32 containing the index of the current instance from which to start searching.

Return Value

A Int32 containing a positive value equal to the index of the first occurrence of an element of anyOf in the current instance; otherwise, -1 if no element of anyOf was found.

Exceptions

Exception Type	Condition
ArgumentNullException	anyOf is a null reference.
ArgumentOutOfRangeException	startIndex is greater than the length of the current instance

Description

This method is case-sensitive.

See Also

System.String Class, System Namespace

anyOf

An array containing the Unicode characters to seek.

startIndex

A Int32 containing the index of the current instance from which to start searching.

count

A Int32 containing the range of the current instance at which to end searching.

Return Value

A Int32 containing a positive value equal to the index of the first occurrence of an element of anyOf in the current instance; otherwise, -1 if no element of anyOf was found.

Exceptions

Exception Type	Condition
ArgumentNullException	anyOf is a null reference.
ArgumentOutOfRangeException	startIndex or count is negative. -or- startIndex + count is greater than the length of the current instance.

Description

The search begins at startIndex and continues until startIndex + count - 1. The character at startIndex + count is not included in the search.

This method is case-sensitive.

See Also

System.String Class, System Namespace

Returns a String equivalent to the current instance with a specified String inserted at the specified position.

Parameters

startIndex

A Int32 containing the index of the insertion.

value

The String to insert.

Return Value

A new String that is equivalent to the current string with value inserted at index startIndex.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex is greater than the length of the current instance.

Description

In the new string returned by this method, the first character of value is at startIndex, and all characters in the current string from startIndex to the end are inserted in the new string after the last character of value.

See Also

System.String Class, System Namespace

Retrieves the system's reference to a specified String.

Parameters

str

A String.

Return Value

The String reference to str.

Exceptions

Exception Type	Condition
ArgumentNullException	str is a null reference.

Description

Instances of each unique literal string constant declared in a program, as well as any unique instance of String you add programmatically are kept in a table, called the "intern pool".

The intern pool conserves string storage. If a literal string constant is assigned to several variables, each variable is set to reference the same constant in the intern pool instead of referencing several different instances of String that have identical values.

This method looks up a specified string in the intern pool. If the string exists, a reference to it is returned. If it does not exist, an instance equal to the specified string is added to the intern pool and a reference that instance is returned.

Example

The following example demonstrates the System.String.Intern(System.String) method.

using System;
using System.Text;
public class StringExample {
 public static void Main() {

     String s1 = "MyTest"; 
        String s2 = new StringBuilder().Append("My").Append("Test").ToString(); 
        String s3 = String.Intern(s2);

        Console.WriteLine(Object.ReferenceEquals(s1, s2));    //different
        Console.WriteLine(Object.ReferenceEquals(s1, s3));    //the same
    }
}

The output is

False

True

See Also

System.String Class, System Namespace

Retrieves a reference to a specified String.

Parameters

str

A String.

Return Value

A String reference to str if it is in the system's intern pool; otherwise, a null reference.

Exceptions

Exception Type	Condition
ArgumentNullException	str is a null reference.

Description

Instances of each unique literal string constant declared in a program, as well as any unique instance of String you add programmatically are kept in a table, called the "intern pool".

The intern pool conserves string storage. If a literal string constant is assigned to several variables, each variable is set to reference the same constant in the intern pool instead of referencing several different instances of String that have identical values.

[Note: This method does not return a Boolean value, but can still be used where a Boolean is needed.]

Example

The following example demonstrates the System.String.IsInterned(System.String) method.

using System;
using System.Text;

public class StringExample {
    public static void Main() {

        String s1 = new StringBuilder().Append("My").Append("Test").ToString(); 

        Console.WriteLine(String.IsInterned(s1) != null);
    }
}

The output is

True

See Also

System.String Class, System Namespace

Concatenates the elements of a specified String array, inserting a separator string between each element pair and yielding a single concatenated string.

Parameters

separator

A String.

value

A String array.

Return Value

A String consisting of the elements of value separated by instances of the separator string.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.

Example

The following example demonstrates the System.String.Join(System.String,System.String[]) method.

using System;
public class StringJoin {
 public static void Main() {
 String[] strAry = { "Red" , "Green" , "Blue" };
 Console.WriteLine( String.Join( " :: ", strAry ) );
 }
}

The output is

Red :: Green :: Blue

See Also

System.String Class, System Namespace

Concatenates a specified separator String between the elements of a specified String array, yielding a single concatenated string.

Parameters

separator

A String.

value

A String array.

startIndex

A Int32 containing the first array element in value to join.

count

A Int32 containing the number of elements in value to join.

Return Value

A String consisting of the specified strings in value joined by separator. Returns System.String.Empty if count is zero, value has no elements, or separator and all the elements of value are Empty .

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex plus count is greater than the number of elements in value.

Example

The following example demonstrates the System.String.Join(System.String,System.String[]) method.

using System;
public class StringJoin {
 public static void Main() {
 String[] strAry = { "Red" , "Green" , "Blue" };
 Console.WriteLine( String.Join( " :: ", strAry, 1, 2 ) );
 }
}

The output is

Green :: Blue

See Also

System.String Class, System Namespace

Returns the index of the last occurrence of a specified String within the current instance, starting at a given position.

Parameters

value

A String .

startIndex

A Int32 containing the index of the current instance from which to start searching.

Return Value

A Int32 that indicates the result of the search for value in the current instance as follows:

Return Value	Description
A zero-based number equal to the index of the start of the last substring in the current instance that is equal to value .	value was found.
-1	value was not found.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex is less than zero or greater than or equal to the length of the current instance.

Description

This method searches for the last occurrence of the specified String between the start of the string and the indicated index.

This method is case-sensitive.

See Also

System.String Class, System Namespace

Returns the index of the last occurrence of a specified String in the provided range of the current instance.

Parameters

value

The substring to search for.

startIndex

A Int32 containing the index of the current instance from which to start searching.

count

A Int32 containing the range of the current instance at which to end searching.

Return Value

A Int32 that indicates the result of the search for value in the current instance as follows:

Return Value	Description
A zero-based number equal to the index of the start of the last substring in the current instance that is equal to value .	value was found.
-1	value was not found.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex or count is less than zero. -or- startIndex - count is smaller than -1.

Description

The search begins at startIndex and continues until startIndex - count + 1.

This method is case-sensitive.

See Also

System.String Class, System Namespace

Returns the index of the last occurrence of a specified String within the current instance.

Parameters

value

A String .

Return Value

A Int32 that indicates the result of the search for value in the current instance as follows:

Return Value	Description
A zero-based number equal to the index of the start of the last substring in the current instance that is equal to value .	value was found.
-1	value was not found.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.

Description

The search is case-sensitive.

See Also

System.String Class, System Namespace

value

A Unicode character to locate.

startIndex

A Int32 containing the index of the current instance from which to start searching.

count

A Int32 containing the range of the current instance at which to end searching.

Return Value

A Int32 containing the index of the last occurrence of value in the current instance if found between startIndex and (startIndex - count + 1); otherwise, -1.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex or count is less than zero. -or- startIndex - count is less than -1.

Description

This method is case-sensitive.

See Also

System.String Class, System Namespace

value

A Unicode character to locate.

startIndex

A Int32 containing the index in the current instance from which to begin searching.

Return Value

A Int32 containing the index of the last occurrence of value in the current instance, if found; otherwise, -1.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.
ArgumentOutOfRangeException	startIndex is less than zero or greater than the length of the current instance.

Description

This method searches for the last occurrence of the specified character between the start of the string and the indicated index.

This method is case-sensitive.

Example

The following example demonstrates the System.String.LastIndexOf(System.Char) method.

using System;
public class StringLastIndexOfTest {
   public static void Main() {
      String str = "aa bb cc dd";
      
      Console.WriteLine( str.LastIndexOf('d', 8) );
      Console.WriteLine( str.LastIndexOf('b', 8) );
   }
}

The output is

-1

4

See Also

System.String Class, System Namespace

A Int32 containing the index of the last occurrence of value in the current instance, if found; otherwise, -1.

Description

This method is case-sensitive.

See Also

System.String Class, System Namespace

A Int32 containing the index of the last occurrence of any element of anyOf in the current instance, if found; otherwise, -1.

Exceptions

Exception Type	Condition
ArgumentNullException	anyOf is a null reference.

Description

This method is case-sensitive.

See Also

System.String Class, System Namespace

anyOf

An array of Unicode characters.

startIndex

A Int32 containing the index of the current instance from which to start searching.

Return Value

A Int32 containing the index of the last occurrence of any element of anyOf in the current instance, if found; otherwise, -1.

Exceptions

Exception Type	Condition
ArgumentNullException	anyOf is a null reference.
ArgumentOutOfRangeException	startIndex is less than zero or greater than or equal to the length of the current instance.

Description

This method searches for the last occurrence of the specified characters between the start of the string and the indicated index.

This method is case-sensitive.

See Also

System.String Class, System Namespace

anyOf

An array of Unicode characters.

startIndex

A Int32 containing the index of the current instance from which to start searching.

count

A Int32 containing the range of the current instance at which to end searching.

Return Value

A Int32 containing the index of the last occurrence of any element of anyOf if found between startIndex and (startIndex - count + 1); otherwise, -1.

Exceptions

Exception Type	Condition
ArgumentNullException	anyOf is a null reference.
ArgumentOutOfRangeException	startIndex or count is less than zero. -or- startIndex - count is smaller than -1.

Description

The search begins at startIndex and continues until startIndex - count + 1. The character at startIndex - count is not included in the search.

This method is case-sensitive.

See Also

System.String Class, System Namespace

totalWidth

A Int32 containing the number of characters in the resulting string.

Return Value

A new String that is equivalent to the current instance right-aligned and padded on the left with as many spaces as needed to create a length of totalWidth. If totalWidth is less than the length of the current instance, returns a new String that is identical to the current instance.

Exceptions

Exception Type	Condition
ArgumentException	totalWidth is less than zero.

Description

[Note: A space in Unicode format is defined as the hexadecimal value 0x20.]

See Also

System.String Class, System Namespace

totalWidth

A Int32 containing the number of characters in the resulting string.

paddingChar

A Char that specifies the padding character to use.

Return Value

A new String that is equivalent to the current instance right-aligned and padded on the left with as many paddingChar characters as needed to create a length of totalWidth . If totalWidth is less than the length of the current instance, returns a new String that is identical to the current instance.

Exceptions

Exception Type	Condition
ArgumentException	totalWidth is less than zero.

See Also

System.String Class, System Namespace

totalWidth

A Int32 containing the number of characters in the resulting string.

paddingChar

A Char that specifies the padding character to use.

Return Value

A new String that is equivalent to the current instance left aligned and padded on the right with as many paddingChar characters as needed to create a length of totalWidth. If totalWidth is less than the length of the current instance, returns a new String that is identical to the current instance.

Exceptions

Exception Type	Condition
ArgumentException	totalWidth is less than zero.

See Also

System.String Class, System Namespace

totalWidth

A Int32 containing the number of characters in the resulting string.

Return Value

A new String that is equivalent to this instance left aligned and padded on the right with as many spaces as needed to create a length of totalWidth. If totalWidth is less than the length of the current instance, returns a new String that is identical to the current instance.

Exceptions

Exception Type	Condition
ArgumentException	totalWidth is less than zero.

See Also

System.String Class, System Namespace

startIndex

A Int32 containing the index of the current instance from which to start deleting characters.

count

A Int32 containing the number of characters to delete.

Return Value

A new String that is equivalent to the current instance without the specified range characters.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex or count is less than zero. -or- startIndex plus count is greater than the length of the current instance.

See Also

System.String Class, System Namespace

oldValue

A String containing the string value to be replaced.

newValue

A String containing the string value to replace all occurrences of oldValue. Can be a null reference.

Return Value

A String equivalent to the current instance with all occurrences of oldValue replaced with newValue. If the replacement value is a null reference, the specified substring is removed.

See Also

System.String Class, System Namespace

A String equivalent to the current instance with all occurrences of oldChar replaced with newChar.

See Also

System.String Class, System Namespace

separator

A Char array of delimiters. Can be a null reference.

Return Value

A String array containing the results of the split operation as follows:

Return Value	Description
A single-element array containing the current instance.	None of the elements of separator are contained in the current instance.
A multi-element String array, each element of which is a substring of the current instance that was delimited by one or more characters in separator.	At least one element of separator is contained in the current instance.
A multi-element String array, each element of which is a substring of the current instance that was delimited by white space characters.	The current instance contains white space characters and separator is a null reference or an empty array.

Description

System.String.Empty is returned for any substring where two delimiters are adjacent or a delimiter is found at the beginning or end of the current instance.

Delimiter characters are not included in the substrings.

See Also

System.String Class, System Namespace

separator

An array of Unicode characters that delimit the substrings in the current instance, an empty array containing no delimiters, or a null reference.

count

A Int32 containing the maximum number of array elements to return.

Return Value

A String array containing the results of the split operation as follows:

Return Value	Description
A single-element array containing the current instance.	None of the elements of separator are contained in the current instance.
A multi-element String array, each element of which is a substring of the current instance that was delimited by one or more characters in separator	At least one element of separator is contained in the current instance.
A multi-element String array, each element of which is a substring of the current instance that was delimited by white space characters.	The current instance contains white space characters and separator is a null reference or an empty array.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	count is negative.

Description

System.String.Empty is returned for any substring where two delimiters are adjacent or a delimiter is found at the beginning or end of the current instance.

Delimiter characters are not included in the substrings.

If there are more substrings in the current instance than the maximum specified number, the first count -1 elements of the array contain the first count - 1 substrings. The remaining characters in the current instance are returned in the last element of the array.

See Also

System.String Class, System Namespace

Returns a Boolean value that indicates whether the start of the current instance matches the specified String.

Parameters

value

A String .

Return Value

true if the start of the current instance is equal to value; false if value is not equal to the start of the current instance or is longer than the current instance.

Exceptions

Exception Type	Condition
ArgumentNullException	value is a null reference.

Description

This method compares value with the substring at the start of the current instance that has a length of value.Length. If value.Length is greater than the length of the current instance or the relevant substring of the current instance is not equal to value, this method returns false ; otherwise, this method returns true .

The comparison is case-sensitive.

See Also

System.String Class, System Namespace

startIndex

A Int32 containing the index of the start of the substring in the current instance.

length

A Int32 containing the number of characters in the substring.

Return Value

A String containing the substring of the current instance with the specified length that begins at the specified position. Returns System.String.Empty if startIndex is equal to the length of the current instance and length is zero.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	length is greater than the length of the current instance. -or- startIndex or length is less than zero.

See Also

System.String Class, System Namespace

startIndex

A Int32 containing the index of the start of the substring in the current instance.

Return Value

A String equivalent to the substring that begins at startIndex of the current instance. Returns System.String.Empty if startIndex is equal to the length of the current instance.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex is less than zero or greater than the length of the current instance.

See Also

System.String Class, System Namespace

System.String Class, System Namespace

Implemented to support the IEnumerable interface. [Note: For more information, see System.Collections.IEnumerable.GetEnumerator.]

See Also

System.String Class, System Namespace

A Char array whose elements are the individual characters of the current instance. If the current instance is an empty string, the array returned by this method is empty and has a zero length.

See Also

System.String Class, System Namespace

startIndex

A Int32 containing the index of the start of a substring in the current instance.

length

A Int32 containing the length of the substring in the current instance.

Return Value

A Char array whose elements are the length number of characters in the current instance, starting from the index startIndex in the current instance. If the specified length is zero, the entire string is copied starting from the beginning of the current instance, and ignoring the value of startIndex. If the current instance is an empty string, the returned array is empty and has a zero length.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex or length is less than zero. -or- startIndex plus length is greater than the length of the current instance.

See Also

System.String Class, System Namespace

Returns a copy of this String in lowercase.

Return Value

A String in lowercase..

Description

This method takes into account the culture (if any) of the current thread.

See Also

System.String Class, System Namespace

Returns a String representation of the value of the current instance.

Return Value

The current String.

Description

[Note: This method overrides System.Object.ToString.]

See Also

System.String Class, System Namespace

provider

(Reserved) A IFormatProvider interface implementation which supplies culture-specific formatting information.

Return Value

This String .

Description

provider is reserved, and does not currently participate in this operation.

See Also

System.String Class, System Namespace

A new String in uppercase.

See Also

System.String Class, System Namespace

Removes all occurrences of a set of characters provided in a character Array from the beginning and end of the current instance.

Parameters

trimChars

An array of Unicode characters. Can be a null reference.

Return Value

A new String equivalent to the current instance with the characters in trimChars removed from its beginning and end. If trimChars is a null reference, all of the white space characters are removed from the beginning and end of the current instance.

See Also

System.String Class, System Namespace

A new String equivalent to the current instance after white space characters are removed from its beginning and end.

See Also

System.String Class, System Namespace

Removes all occurrences of a set of characters specified in a Unicode character Array from the end of the current instance.

Parameters

trimChars

An array of Unicode characters. Can be a null reference.

Return Value

A new String equivalent to the current instance with characters in trimChars removed from its end. If trimChars is a null reference, white space characters are removed.

See Also

System.String Class, System Namespace

A new String equivalent to the current instance with the characters in trimChars removed from its beginning. If trimChars is a null reference, white space characters are removed.

See Also

System.String Class, System Namespace

Returns a Boolean value indicating whether the two specified string values are equal to each other.

Parameters

a

The first String to compare.

b

The second String to compare.

Return Value

true if a and b represent the same string value; otherwise, false .

See Also

System.String Class, System Namespace

Returns a Boolean value indicating whether the two string values are not equal to each other.

Parameters

a

The first String to compare.

b

The second String to compare.

Return Value

true if a and b do not represent the same string value; otherwise, false .

See Also

System.String Class, System Namespace

System.String Class, System Namespace

System.String Class, System Namespace

A Int32 containing the number of characters in the current instance.

Description

This property is read-only.

Example

The following example demonstrates the System.String.Length property.

using System;
public class StringLengthExample {
 public static void Main() {
 string str = "STRING";
 Console.WriteLine( "The length of string {0} is {1}", str, str.Length );
 }
}

The output is

The length of string STRING is 6

See Also

System.String Class, System Namespace