System.String Class

Assembly: Mscorlib.dll
Namespace: System
Summary
Represents an immutable series of characters.
C# Syntax:
[Serializable]
public sealed class String : IComparable, ICloneable, IConvertible, IEnumerable
Thread Safety
This type is safe for multithreaded operations.
Remarks
An instance of String is said to be immutable because its value cannot be modified once it has been created. Methods that appear to modify a String actually return a new String containing the modification. Use the StringBuilder class if it is necessary to actually modify the contents of a string-like object.

An index is the position of a character within a string, and is counted starting from the first character in the string, which is index position zero. That is, a string index is said to be zero-based.

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

Comparison and search procedures are case-sensitive by default and use the culture associated with the current thread, unless specified otherwise. Uppercase letters evaluate greater than their lowercase equivalents. For more information about the current culture, see the CultureInfo.CurrentCulture topic.

By definition, any String, including the empty string (""), compares greater than null; and two null references compare equal to each other.

Use the String.Compare and String.Equals methods to perform combined reference and value comparisons of Object and String instances. The and relational operators are implemented with the String.Equals method and can also be used to make reference and value comparisons.

The following characters are considered white space when present in a String: hexadecimal 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.

Use the String.Format method to replace each format specification embedded in a parameter string with the formatted string representation of the value of a corresponding object. Format specifications are of the form, { N [, M ][: formatCode ]}, where:

This class implements the IComparable, ICloneable, IConvertible, and IEnumerable interfaces. Use the Convert class for conversions instead of this type's explicit interface member implementation of IConvertible.

Example
The following examples are for illustrative purposes only; they will not run as specified in the comments. The first set of examples shows the use of relational operators.
See also:
System Namespace | IComparable | ICloneable | IConvertible | IEnumerable | StringBuilder | CultureInfo | MSDN: formattingoverview

System.String Member List:

Public Constructors
ctor #1 Overloaded:
.ctor(char* value)

 Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters.
ctor #2 Overloaded:
.ctor(char[] value)

 Initializes a new instance of the String class to the value indicated by an array of Unicode characters.
ctor #3 Overloaded:
.ctor(sbyte* value)

 Initializes a new instance of the String class to the value indicated by a pointer to an array of 8-bit signed integers.
ctor #4 Overloaded:
.ctor(char c, int count)

 Initializes a new instance of the String class to the value indicated by a specified Unicode character repeated a specified number of times.
ctor #5 Overloaded:
.ctor(char* value, int startIndex, int length)

 Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters, a starting character position within that array, and a length.
ctor #6 Overloaded:
.ctor(char[] value, int startIndex, int length)

 Initializes a new instance of the String class to the value indicated by an array of Unicode characters, a starting character position within that array, and a length.
ctor #7 Overloaded:
.ctor(sbyte* value, int startIndex, int length)

 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.
ctor #8 Overloaded:
.ctor(sbyte* value, int startIndex, int length, Encoding enc)

 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, a length, and an Encoding object.
Public Fields
Empty Represents the empty string. This field is read-only.
Public Properties
Chars Read-only

Gets the character at a specified character position in this instance.
Length Read-only

Gets the number of characters in this instance.
Public Methods
Clone Returns a reference to this instance of String.
Compare Overloaded:
Compare(string strA, string strB)

 Compares two specified String objects.
Compare Overloaded:
Compare(string strA, string strB, bool ignoreCase)

 Compares two specified String objects, ignoring or honoring their case.
Compare Overloaded:
Compare(string strA, string strB, bool ignoreCase, CultureInfo culture)

 Compares two specified String objects, ignoring or honoring their case, and honoring culture-specific information about their formatting.
Compare Overloaded:
Compare(string strA, int indexA, string strB, int indexB, int length)

 Compares substrings of two specified String objects.
Compare Overloaded:
Compare(string strA, int indexA, string strB, int indexB, int length, bool ignoreCase)

 Compares substrings of two specified String objects, ignoring or honoring their case.
Compare Overloaded:
Compare(string strA, int indexA, string strB, int indexB, int length, bool ignoreCase, CultureInfo culture)

 Compares substrings of two specified String objects, ignoring or honoring their case, and honoring culture-specific information about their formatting.
CompareOrdinal Overloaded:
CompareOrdinal(string strA, string strB)

 Compares two specified String objects, without considering the local national language or culture.
CompareOrdinal Overloaded:
CompareOrdinal(string strA, int indexA, string strB, int indexB, int length)

 Compares substrings of two specified String objects, without considering the local national language or culture. Parameters specify the length and starting positions of the substrings.
CompareTo Overloaded:
CompareTo(object value)

 Compares this instance with a specified Object.
CompareTo Overloaded:
CompareTo(string strB)

 Compares this instance with a specified String object.
Concat Overloaded:
Concat(object arg0)

 Creates the String representation of a specified object.
Concat Overloaded:
Concat(params object[] args)

 Concatenates the String representations of the elements in a specified Object array.
Concat Overloaded:
Concat(params string[] values)

 Concatenates the elements of a specified String array.
Concat Overloaded:
Concat(object arg0, object arg1)

 Concatenates the String representations of two specified objects.
Concat Overloaded:
Concat(string str0, string str1)

 Concatenates two specified instances of String.
Concat Overloaded:
Concat(object arg0, object arg1, object arg2)

 Concatenates the String representations of three specified objects.
Concat Overloaded:
Concat(string str0, string str1, string str2)

 Concatenates three specified instances of String.
Concat Overloaded:
Concat

 Concatenates the String representations of three specified objects and a variable-length parameter list.
Concat Overloaded:
Concat(string str0, string str1, string str2, string str3)

 Concatenates four specified instances of String.
Copy Creates a new instance of String with the same value as a specified String.
CopyTo Copies a specified number of characters from a specified position in this instance to a specified position in an array of Unicode characters.
EndsWith Determines whether the end of this instance matches the specified String.
Equals Overloaded:
Equals(object obj)

Overridden:
Determines whether this instance of String and a specified object, which must be a String, have the same value.
Equals Overloaded:
Equals(string value)

 Determines whether this instance and a specified String have the same value.
Equals Overloaded:
Equals(string a, string b)

 Determines whether two specified String objects have the same value.
Format Overloaded:
Format(string format, object arg0)

 Replaces the format specification in a specified String with the textual equivalent of the value of a specified Object instance.
Format Overloaded:
Format(string format, params object[] args)

 Replaces the format specification in a specified String with the textual equivalent of the value of a corresponding Object instance in a specified array.
Format Overloaded:
Format(IFormatProvider provider, string format, params object[] args)

 Replaces the format specification in a specified String with the textual equivalent of the value of a corresponding Object instance in a specified array. A specified parameter supplies culture-specific formatting information.
Format Overloaded:
Format(string format, object arg0, object arg1)

 Replaces the format specification in a specified String with the textual equivalent of the value of two specified Object instances.
Format Overloaded:
Format(string format, object arg0, object arg1, object arg2)

 Replaces the format specification in a specified String with the textual equivalent of the value of three specified Object instances.
GetEnumerator Retrieves an object that can iterate through the individual characters in this instance.
GetHashCode Overridden:
Returns the hash code for this instance.
GetType
(inherited from System.Object)		 See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
GetTypeCode Returns the TypeCode for class String.
IndexOf Overloaded:
IndexOf(char value)

 Reports the index of the first occurrence of the specified Unicode character in this instance.
IndexOf Overloaded:
IndexOf(string value)

 Reports the index of the first occurrence of the specified String in this instance.
IndexOf Overloaded:
IndexOf(char value, int startIndex)

 Reports the index of the first occurrence of the specified Unicode character in this instance. The search starts at a specified character position.
IndexOf Overloaded:
IndexOf(string value, int startIndex)

 Reports the index of the first occurrence of the specified String in this instance. The search starts at a specified character position.
IndexOf Overloaded:
IndexOf(char value, int startIndex, int count)

 Reports the index of the first occurrence of the specified character in this instance. The search starts at a specified character position and examines a specified number of character positions.
IndexOf Overloaded:
IndexOf(string value, int startIndex, int count)

 Reports the index of the first occurrence of the specified String in this instance. The search starts at a specified character position and examines a specified number of character positions.
IndexOfAny Overloaded:
IndexOfAny(char[] anyOf)

 Reports the index of the first occurrence in this instance of any character in a specified array of Unicode characters.
IndexOfAny Overloaded:
IndexOfAny(char[] anyOf, int startIndex)

 Reports the index of the first occurrence in this instance of any character in a specified array of Unicode characters. The search starts at a specified character position.
IndexOfAny Overloaded:
IndexOfAny(char[] anyOf, int startIndex, int count)

 Reports the index of the first occurrence in this instance of any character in a specified array of Unicode characters. The search starts at a specified character position and examines a specified number of character positions.
Insert Inserts a specified instance of String at a specified index position in this instance.
Intern Retrieves the system's reference to the specified String.
IsInterned Retrieves a reference to a specified String.
Join Overloaded:
Join(string separator, string[] value)

 Concatenates a specified separator String between each element of a specified String array, yielding a single concatenated string.
Join Overloaded:
Join(string separator, string[] value, int startIndex, int count)

 Concatenates a specified separator String between each element of a specified String array, yielding a single concatenated string. Parameters specify the first array element and number of elements to use.
LastIndexOf Overloaded:
LastIndexOf(char value)

 Reports the index position of the last occurrence of a specified Unicode character within this instance.
LastIndexOf Overloaded:
LastIndexOf(string value)

 Reports the index position of the last occurrence of a specified String within this instance.
LastIndexOf Overloaded:
LastIndexOf(char value, int startIndex)

 Reports the index position of the last occurrence of a specified Unicode character within this instance. The search starts at a specified character position.
LastIndexOf Overloaded:
LastIndexOf(string value, int startIndex)

 Reports the index position of the last occurrence of a specified String within this instance. The search starts at a specified character position.
LastIndexOf Overloaded:
LastIndexOf(char value, int startIndex, int count)

 Reports the index position of the last occurrence of the specified Unicode character in a substring within this instance. The search starts at a specified character position and examines a specified number of character positions.
LastIndexOf Overloaded:
LastIndexOf(string value, int startIndex, int count)

 Reports the index position of the last occurrence of a specified String within this instance. The search starts at a specified character position and examines a specified number of character positions.
LastIndexOfAny Overloaded:
LastIndexOfAny(char[] anyOf)

 Reports the index position of the last occurrence in this instance of one or more characters specified in a Unicode array.
LastIndexOfAny Overloaded:
LastIndexOfAny(char[] anyOf, int startIndex)

 Reports the index position of the last occurrence in this instance of one or more characters specified in a Unicode array. The search starts at a specified character position.
LastIndexOfAny Overloaded:
LastIndexOfAny(char[] anyOf, int startIndex, int count)

 Reports the index position of the last occurrence in this instance of one or more characters specified in a Unicode array. The search starts at a specified character position and examines a specified number of character positions.
PadLeft Overloaded:
PadLeft(int totalWidth)

 Right-aligns the characters in this instance, padding with spaces on the left for a specified total length.
PadLeft Overloaded:
PadLeft(int totalWidth, char paddingChar)

 Right-aligns the characters in this instance, padding on the left with a specified Unicode character for a specified total length.
PadRight Overloaded:
PadRight(int totalWidth)

 Left-aligns the characters in this string, padding with spaces on the right, for a specified total length.
PadRight Overloaded:
PadRight(int totalWidth, char paddingChar)

 Left-aligns the characters in this string, padding on the right with a specified Unicode character, for a specified total length.
Remove Deletes a specified number of characters from this instance beginning at a specified position.
Replace Overloaded:
Replace(char oldChar, char newChar)

 Replaces all occurrences of a specified Unicode character in this instance with another specified Unicode character.
Replace Overloaded:
Replace(string oldValue, string newValue)

 Replaces all occurrences of a specified String in this instance, with another specified String.
Split Overloaded:
Split(params char[] separator)

 Identifies the substrings in this instance that are delimited by one or more characters specified in an array, then places the substrings into a String array.
Split Overloaded:
Split(char[] separator, int count)

 Identifies the substrings in this instance that are delimited by one or more characters specified in an array, then places the substrings into a String array. A parameter specifies the maximum number of array elements to return.
StartsWith Determines whether the beginning of this instance matches the specified String.
Substring Overloaded:
Substring(int startIndex)

 Retrieves a substring from this instance. The substring starts at a specified character position.
Substring Overloaded:
Substring(int startIndex, int length)

 Retrieves a substring from this instance. The substring starts at a specified character position and has a specified length.
ToCharArray Overloaded:
ToCharArray()

 Copies the characters in this instance to a Unicode character array.
ToCharArray Overloaded:
ToCharArray(int startIndex, int length)

 Copies the characters in a specified substring in this instance to a Unicode character array.
ToLower Overloaded:
ToLower()

 Returns a copy of this String in lowercase.
ToLower Overloaded:
ToLower(CultureInfo culture)

 Returns a copy of this String in lowercase, taking into account specified culture-specific information.
ToString Overloaded:
ToString()

Overridden:
Returns this instance of String; no actual conversion is performed.
ToString Overloaded:
ToString(IFormatProvider provider)

 Returns this instance of String; no actual conversion is performed.
ToUpper Overloaded:
ToUpper()

 Returns a copy of this String in uppercase, using default properties.
ToUpper Overloaded:
ToUpper(CultureInfo culture)

 Returns a copy of this String in uppercase, taking into account culture-specific information.
Trim Overloaded:
Trim()

 Removes all occurrences of white space characters from the beginning and end of this instance.
Trim Overloaded:
Trim(params char[] trimChars)

 Removes all occurrences of a set of characters specified in a Unicode character array from the beginning and end of this instance.
TrimEnd Removes all occurrences of a set of characters specified in a Unicode character array from the end of this instance.
TrimStart Removes all occurrences of a set of characters specified in a Unicode character array from the beginning of this instance.
Public Operators and Type Conversions
op_Equality Determines whether two specified String objects have the same value.
op_Inequality Determines whether two specified String objects have different values.
Protected Methods
Finalize
(inherited from System.Object)		 See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)		 See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:

System.String Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
unsafe public String(
   char* value
);
Parameters:

value

A pointer to a null terminated array of Unicode characters.

Remarks
If value is a null pointer, an String.Empty instance is initialized.

This constructor copies the sequence of Unicode charaters 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.

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

See also:
Char

Return to top

Overloaded ctor #2
Summary
Initializes a new instance of the String class to the value indicated by an array of Unicode characters.
C# Syntax:
public String(
   char[] value
);
Parameters:

value

An array of Unicode characters.

Remarks
If value is null or contains no element, an String.Empty instance is initialized.
See also:
Char

Return to top

Overloaded ctor #3
Summary
Initializes a new instance of the String class to the value indicated by a pointer to an array of 8-bit signed integers.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
unsafe public String(
   sbyte* value
);
Parameters:

value

A pointer to a null terminated array of 8-bit signed integers.

Remarks
If value is a null pointer, an String.Empty instance is initialized.

This constructor copies the sequence of charaters 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.

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

See also:
SByte

Return to top

Overloaded ctor #4
Summary
Initializes a new instance of the String class to the value indicated by a specified Unicode character repeated a specified number of times.
C# Syntax:
public String(
   char c,
   int count
);
Parameters:

c

A Unicode character.

count

The number of times c occurs.

Exceptions
Exception Type Condition
ArgumentOutOfRangeException count is less than zero.
Remarks
If count is zero, an String.Empty instance is initialized.
See also:
Char | Int32

Return to top

Overloaded ctor #5
Summary
Initializes a new instance of the String class to the value indicated by a specified pointer to an array of Unicode characters, a starting character position within that array, and a length.
This member is not CLS Compliant

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

value

A pointer to an array of Unicode characters.

startIndex

The starting position within value.

length

The number of characters within value to use.

Exceptions
Exception Type Condition
ArgumentOutOfRangeException startIndex or length is less than zero.

-or-

value is a null pointer and length is not zero.
Remarks
If length is zero, an String.Empty instance is initialized.

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.

See also:
Char | Int32

Return to top

Overloaded ctor #6
Summary
Initializes a new instance of the String class to the value indicated by an array of Unicode characters, a starting character position within that array, and a length.
C# Syntax:
public String(
   char[] value,
   int startIndex,
   int length
);
Parameters:

value

An array of Unicode characters.

startIndex

The starting position within value.

length

The number of characters within value to use.

Exceptions
Exception Type Condition
ArgumentNullException value is null, and startIndex and length are not zero.
ArgumentOutOfRangeException startIndex or length is less than zero.

-or-

The sum of startIndex and length is greater than the number of elements in value.
Remarks
If length is zero, an String.Empty instance is initialized.

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

See also:
Char | Int32

Return to top

Overloaded ctor #7
Summary
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 member is not CLS Compliant

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

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
Exception Type Condition
ArgumentOutOfRangeException startIndex or length is less than zero.

-or-

value is a null pointer and length is not zero.
Remarks
If length is zero, an String.Empty instance is initialized.

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.

See also:
SByte | Int32

Return to top

Overloaded ctor #8
Summary
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, a length, and an Encoding object.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
unsafe public String(
   sbyte* value,
   int startIndex,
   int length,
   Encoding enc
);
Parameters:

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.

enc

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

Exceptions
Exception Type Condition
ArgumentOutOfRangeException startIndex or length is less than zero.
Remarks
If value is a null pointer, an String.Empty instance is initialized.
See also:
SByte | Int32

Return to top

Field: Empty
Summary
Represents the empty string. This field is read-only.
C# Syntax:
public static readonly string Empty;
Remarks
The value of this field is the zero-length string, "".

Return to top

Property: Chars (read-only)
Summary
Gets the character at a specified character position in this instance.
C# Syntax:
No member name public char this[int index] {get;}
Parameters:

index

A character position in this instance.

Exceptions
Exception Type Condition
IndexOutOfRangeException index is greater than or equal to the length of this object or less than zero.
Remarks
index is zero-based.
See also:
Char | String.GetEnumerator | Int32

Return to top

Property: Length (read-only)
Summary
Gets the number of characters in this instance.
C# Syntax:
public int Length {get;}
See also:
Int32

Return to top

Method: Clone()
Summary
Returns a reference to this instance of String.
C# Syntax:
public object Clone();
Return Value:
This instance of String.
Implements:
ICloneable.Clone
Remarks
The return value is not an independent copy of this instance; it is simply another view of the same data. Use the String.Copy or String.CopyTo method to create a separate String object with the same value as this instance.
See also:
Object | String.Copy | String.CopyTo

Return to top

Overloaded Method: Compare(
   string strA,
   string strB
)
Summary
Compares two specified String objects.
C# Syntax:
public static int Compare(
   string strA,
   string strB
);
Parameters:

strA

The first String.

strB

The second String.

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Meaning
Less than zero is less than .
Zero equals .
Greater than zero is greater than .
Remarks
By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.

This method performs a case-sensitive operation. The method uses the current culture to determine the ordering of individual characters. Uppercase letters evaluate greater than their lowercase equivalents. The two strings are compared on a character-by-character basis.

See also:
Int32 | String.CompareOrdinal | String.CompareTo

Return to top

Overloaded Method: Compare(
   string strA,
   string strB,
   bool ignoreCase
)
Summary
Compares two specified String objects, ignoring or honoring their case.
C# Syntax:
public static int Compare(
   string strA,
   string strB,
   bool ignoreCase
);
Parameters:

strA

The first String.

strB

The second String.

ignoreCase

A Boolean indicating a case-sensitive or insensitive comparison. (true indicates a case-insensitive comparison.)

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Meaning
Less than zero is less than .
Zero equals .
Greater than zero is greater than .
Remarks
By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.

This method uses the current culture to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

See also:
Int32 | String.CompareOrdinal | String.CompareTo | CompareInfo.IsPrefix

Return to top

Overloaded Method: Compare(
   string strA,
   string strB,
   bool ignoreCase,
   CultureInfo culture
)
Summary
Compares two specified String objects, ignoring or honoring their case, and honoring culture-specific information about their formatting.
C# Syntax:
public static int Compare(
   string strA,
   string strB,
   bool ignoreCase,
   CultureInfo culture
);
Parameters:

strA

The first String.

strB

The second String.

ignoreCase

A Boolean indicating a case-sensitive or insensitive comparison. (true indicates a case-insensitive comparison.)

culture

A CultureInfo object that supplies culture-specific formatting information.

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Meaning
Less than zero is less than .
Zero equals .
Greater than zero is greater than .
Exceptions
Exception Type Condition
ArgumentNullException culture is null.
Remarks
culture specifies a CultureInfo object, which provides culture-specific information that can affect the comparison.

By definition, any String, including the empty string, compares greater than a null reference; and two null references compare equal to each other.

See also:
Int32 | String.CompareOrdinal | String.CompareTo | CompareInfo.IsPrefix | Boolean

Return to top

Overloaded Method: Compare(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length
)
Summary
Compares substrings of two specified String objects.
C# Syntax:
public static int Compare(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length
);
Parameters:

strA

The first String.

indexA

The position of the substring within strA.

strB

The second String.

indexB

The position of the substring within strB.

length

The maximum number of characters in the substrings to compare.

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Meaning
Less than zero The substring in is less than the substring in .
Zero The substrings are equal, or is zero.
Greater than zero The substring in is greater than the substring in .
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.
Remarks
indexA and indexB are zero-based.

length cannot be negative. If length is zero, then zero is returned.

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

By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.

This method performs a case-sensitive operation. The method uses the current culture to determine the ordering of individual characters. Uppercase letters evaluate greater than their lowercase equivalents. The two strings are compared on a character-by-character basis.

See also:
Int32 | String.CompareOrdinal | String.CompareTo

Return to top

Overloaded Method: Compare(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length,
   bool ignoreCase
)
Summary
Compares substrings of two specified String objects, ignoring or honoring their case.
C# Syntax:
public static int Compare(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length,
   bool ignoreCase
);
Parameters:

strA

The first String.

indexA

The position of the substring within strA.

strB

The second String.

indexB

The position of the substring within strB.

length

The maximum number of characters in the substrings to compare.

ignoreCase

A Boolean indicating a case-sensitive or insensitive comparison. (true indicates a case-insensitive comparison.)

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Type Condition
Less than zero The substring in is less than the substring in .
Zero The substrings are equal, or is zero.
Greater than zero The substring in is greater than the substring in .
Exceptions
Exception Type Condition
ArgumentOutOfRangeException Either index is outside the series of characters to be compared.

-or-

length is negative.
Remarks
indexA and indexB are zero-based.length cannot be negative.

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

By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.

This method uses the current culture to determine the ordering of individual characters. The two strings are compared on a character-by-character basis.

See also:
Int32 | String.CompareOrdinal | String.CompareTo

Return to top

Overloaded Method: Compare(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length,
   bool ignoreCase,
   CultureInfo culture
)
Summary
Compares substrings of two specified String objects, ignoring or honoring their case, and honoring culture-specific information about their formatting.
C# Syntax:
public static int Compare(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length,
   bool ignoreCase,
   CultureInfo culture
);
Parameters:

strA

The first String.

indexA

The position of the substring within strA.

strB

The second String.

indexB

The position of the substring within the strB.

length

The maximum number of characters in the substrings to compare.

ignoreCase

A Boolean indicating a case-sensitive or insensitive comparison. (true indicates a case-insensitive comparison.)

culture

A CultureInfo object that supplies culture-specific formatting information.

Return Value:
An integer indicating the lexical relationship between the two comparands.

Value Type Condition
Less than zero The substring in is less than the substring in .
Zero The substrings are equal, or is zero.
Greater than zero The substring in is greater than the substring in .
Exceptions
Exception Type Condition
ArgumentNullException culture is null.
ArgumentOutOfRangeException Either index is outside the series of characters to be compared.

-or-

length is negative.
Remarks
culture specifies a CultureInfo object, which provides culture-specific information that can affect the comparison.length cannot be negative.

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

By definition, any String, including the empty string, compares greater than a null reference; and two null references compare equal to each other.

See also:
Int32 | String.CompareOrdinal | String.CompareTo

Return to top

Overloaded Method: CompareOrdinal(
   string strA,
   string strB
)
Summary
Compares two specified String objects, without considering the local national language or culture.
C# Syntax:
public static int CompareOrdinal(
   string strA,
   string strB
);
Parameters:

strA

The first String.

strB

The second String.

Return Value:
An integer indicating the lexical relationship between the two comparands.

Permission Description
Less than zero is less than .
Zero and are equal.
Greater than zero is greater than .
Remarks
By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.
See also:
Int32 | String.Compare | String.CompareTo

Return to top

Overloaded Method: CompareOrdinal(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length
)
Summary
Compares substrings of two specified String objects, without considering the local national language or culture. Parameters specify the length and starting positions of the substrings.
C# Syntax:
public static int CompareOrdinal(
   string strA,
   int indexA,
   string strB,
   int indexB,
   int length
);
Parameters:

strA

The first String.

indexA

The starting index of the substring in strA.

strB

The second String.

indexB

The starting index of the substring in strB.

length

The maximum number of characters in the substrings to compare.

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Type Condition
Less than zero The substring in is less than the substring in .
Zero The substrings are equal, or is zero.
Greater than zero The substring in is greater than the substring in .
Exceptions
Exception Type Condition
ArgumentOutOfRangeException indexA, indexB, or length is negative.

-or-

The sum of indexA and length is greater than strA.Length.

-or-

The sum of indexB and length is greater than strB.Length.
Remarks
By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.

indexA, indexB, and length must be positive.

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

See also:
String.Compare | String.CompareTo | Int32

Return to top

Overloaded Method: CompareTo(
   object value
)
Summary
Compares this instance with a specified Object.
C# Syntax:
public int CompareTo(
   object value
);
Parameters:

value

An Object that evaluates to a String.

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Condition
Less than zero This instance is less than .
Zero This instance is equal to .
Greater than zero This instance is greater than value. -or- value is null.
Exceptions
Exception Type Condition
ArgumentException value is not a String.
Implements:
IComparable.CompareTo
Remarks
value must be a String object.

By definition, any String, including the empty string, compares greater than null; and two null references compare equal to each other.

This method performs a case-sensitive operation. The method uses the current culture to determine the ordering of individual characters. Uppercase letters evaluate greater than their lowercase equivalents. The two strings are compared on a character-by-character basis.

See also:
String.Compare | String.CompareOrdinal

Return to top

Overloaded Method: CompareTo(
   string strB
)
Summary
Compares this instance with a specified String object.
C# Syntax:
public int CompareTo(
   string strB
);
Parameters:

strB

A String.

Return Value:
A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value Condition
Less than zero This instance is less than .
Zero This instance is equal to .
Greater than zero This instance is greater than value. -or- value is null.
Remarks
By definition, any String, including the empty string, compares greater than a null reference; and two null references compare equal to each other.
See also:
String.Compare | String.CompareOrdinal

Return to top

Overloaded Method: Concat(
   object arg0
)
Summary
Creates the String representation of a specified object.
C# Syntax:
public static string Concat(
   object arg0
);
Parameters:

arg0

An Object or null.

Return Value:
The String representation of the value of arg0.
Remarks
An String.Empty string is used in place of any null argument.
See also:
Object | String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   params object[] args
)
Summary
Concatenates the String representations of the elements in a specified Object array.
C# Syntax:
public static string Concat(
   params object[] args
);
Parameters:

args

An Object array.

Return Value:
The concatenated String representations of the values of the elements in args.
Exceptions
Exception Type Condition
ArgumentNullException args is null.
Remarks
An String.Empty string is used in place of any null object in the array.
See also:
Object | String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   params string[] values
)
Summary
Concatenates the elements of a specified String array.
C# Syntax:
public static string Concat(
   params string[] values
);
Parameters:

values

An array of String instances.

Return Value:
The concatenated elements of values.
Exceptions
Exception Type Condition
ArgumentNullException values is null.
Remarks
An String.Empty string is used in place of any null object in the array.
See also:
String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   object arg0,
   object arg1
)
Summary
Concatenates the String representations of two specified objects.
C# Syntax:
public static string Concat(
   object arg0,
   object arg1
);
Parameters:

arg0

The first Object.

arg1

The second Object.

Return Value:
The concatenated String representations of the values of arg0 and arg1.
Remarks
An String.Empty string is used in place of any null argument.

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

See also:
Object | String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   string str0,
   string str1
)
Summary
Concatenates two specified instances of String.
C# Syntax:
public static string Concat(
   string str0,
   string str1
);
Parameters:

str0

The first String.

str1

The second String.

Return Value:
The concatenation of str0 and str1.
Remarks
An String.Empty string is used in place of any null argument.
See also:
String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   object arg0,
   object arg1,
   object arg2
)
Summary
Concatenates the String representations of three specified objects.
C# Syntax:
public static string Concat(
   object arg0,
   object arg1,
   object arg2
);
Parameters:

arg0

The first Object.

arg1

The second Object.

arg2

The third Object.

Return Value:
The concatenated String representations of the values of arg0, arg1, and arg2.
Remarks
An String.Empty string is used in place of any null argument.
See also:
Object | String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   string str0,
   string str1,
   string str2
)
Summary
Concatenates three specified instances of String.
C# Syntax:
public static string Concat(
   string str0,
   string str1,
   string str2
);
Parameters:

str0

The first String.

str1

The second String.

str2

The third String.

Return Value:
The concatenation of str0, str1, and str2.
Remarks
An String.Empty string is used in place of any null argument.
See also:
String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat
Summary
Concatenates the String representations of three specified objects and a variable-length parameter list.
Parameters:

arg0

The first Object.

arg1

The second Object.

arg2

The third Object.

arg3

The fourth Object.

Return Value:
The concatenated String representations of the values of arg0, arg1, arg2, arg3, and zero or more objects specified in a variable-length parameter list.
Remarks
Additional arguments can be included in a variable-length parameter list.

An String.Empty string is used in place of any null argument.

See also:
Object | ArgIterator | String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Overloaded Method: Concat(
   string str0,
   string str1,
   string str2,
   string str3
)
Summary
Concatenates four specified instances of String.
C# Syntax:
public static string Concat(
   string str0,
   string str1,
   string str2,
   string str3
);
Parameters:

str0

The first String.

str1

The second String.

str2

The third String.

str3

The fourth String.

Return Value:
The concatenation of str0, str1, str2, and str3.
Remarks
An String.Empty string is used in place of any null object in the array.
See also:
String.Insert | String.Join | String.Remove | String.Replace | String.Split | String.Substring | String.Trim

Return to top

Method: Copy(
   string str
)
Summary
Creates a new instance of String with the same value as a specified String.
C# Syntax:
public static string Copy(
   string str
);
Parameters:

str

The String to copy.

Return Value:
A new String with the same value as str.
Exceptions
Exception Type Condition
ArgumentNullException str is null.
See also:
String.Empty | DBNull

Return to top

Method: CopyTo(
   int sourceIndex,
   char[] destination,
   int destinationIndex,
   int count
)
Summary
Copies a specified number of characters from a specified position in this instance to a specified position in an array of Unicode characters.
C# Syntax:
public void CopyTo(
   int sourceIndex,
   char[] destination,
   int destinationIndex,
   int count
);
Parameters:

sourceIndex

A character position in this instance.

destination

An array of Unicode characters.

destinationIndex

An array element in destination.

count

The number of characters in this instance to copy to destination.

Exceptions
Exception Type Condition
ArgumentNullException destination is null.
ArgumentOutOfRangeException sourceIndex, destinationIndex, or count is negative

-or-

count is greater than the length of the substring from startIndex to the end of this instance

-or-

count is greater than the length of the subarray from destinationIndex to the end of destination
Remarks
count characters are copied from the sourceIndex position of this instance to the destinationIndex position of destination.

sourceIndex and destinationIndex are zero-based.

See also:
Char | Int32 | String.Insert | String.Substring

Return to top

Method: EndsWith(
   string value
)
Summary
Determines whether the end of this instance matches the specified String.
C# Syntax:
public bool EndsWith(
   string value
);
Parameters:

value

A String.

Return Value: </