Char Structure

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

Represents a Unicode character.

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

Syntax

Public Structure Char _
    Implements IComparable, IComparable(Of Char),  _
    IConvertible, IEquatable(Of Char)

public struct Char : IComparable, IComparable<char>, 
    IConvertible, IEquatable<char>

The Char type exposes the following members.

Methods

	Name	Description
	CompareTo(Char)	Compares this instance to a specified Char object and returns an integer that indicates whether this instance precedes, follows, or has the same position in the sort order as the specified Char value.
	CompareTo(Object)	Compares this instance to a specified object and returns an integer that indicates whether this instance precedes, follows, or has the same position in the sort order as the specified object.
	ConvertFromUtf32	Converts the specified Unicode code point into a UTF-16 encoded string.
	ConvertToUtf32(Char, Char)	Converts the value of a UTF-16 encoded surrogate pair into a Unicode code point.
	ConvertToUtf32(String, Int32)	Converts the value of a UTF-16 encoded character or surrogate pair at a specified position in a string into a Unicode code point.
	Equals(Char)	Returns a value indicating whether this instance is equal to the specified Char object.
	Equals(Object)	Returns a value indicating whether this instance is equal to a specified object. (Overrides ValueType..::.Equals(Object).)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Returns the hash code for this instance. (Overrides ValueType..::.GetHashCode()()().)
	GetNumericValue(Char)	Converts the specified numeric Unicode character to a double-precision floating point number.
	GetNumericValue(String, Int32)	Converts the numeric Unicode character at the specified position in a specified string to a double-precision floating point number.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GetTypeCode	Returns the TypeCode for value type Char.
	GetUnicodeCategory(Char)	Categorizes a specified Unicode character into a group identified by one of the UnicodeCategory values.
	GetUnicodeCategory(String, Int32)	Categorizes the character at the specified position in a specified string into a group identified by one of the UnicodeCategory values.
	IsControl(Char)	Indicates whether the specified Unicode character is categorized as a control character.
	IsControl(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a control character.
	IsDigit(Char)	Indicates whether the specified Unicode character is categorized as a decimal digit.
	IsDigit(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a decimal digit.
	IsHighSurrogate(Char)	Indicates whether the specified Char object is a high surrogate.
	IsHighSurrogate(String, Int32)	Indicates whether the Char object at the specified position in a string is a high surrogate.
	IsLetter(Char)	Indicates whether the specified Unicode character is categorized as a Unicode letter.
	IsLetter(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a Unicode letter.
	IsLetterOrDigit(Char)	Indicates whether the specified Unicode character is categorized as a letter or a decimal digit.
	IsLetterOrDigit(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a letter or a decimal digit.
	IsLower(Char)	Indicates whether the specified Unicode character is categorized as a lowercase letter.
	IsLower(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a lowercase letter.
	IsLowSurrogate(Char)	Indicates whether the specified Char object is a low surrogate.
	IsLowSurrogate(String, Int32)	Indicates whether the Char object at the specified position in a string is a low surrogate.
	IsNumber(Char)	Indicates whether the specified Unicode character is categorized as a number.
	IsNumber(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a number.
	IsPunctuation(Char)	Indicates whether the specified Unicode character is categorized as a punctuation mark.
	IsPunctuation(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a punctuation mark.
	IsSeparator(Char)	Indicates whether the specified Unicode character is categorized as a separator character.
	IsSeparator(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a separator character.
	IsSurrogate(Char)	Indicates whether the specified character has a surrogate code unit.
	IsSurrogate(String, Int32)	Indicates whether the character at the specified position in a specified string has a surrogate code unit.
	IsSurrogatePair(Char, Char)	Indicates whether the two specified Char objects form a surrogate pair.
	IsSurrogatePair(String, Int32)	Indicates whether two adjacent Char objects at a specified position in a string form a surrogate pair.
	IsSymbol(Char)	Indicates whether the specified Unicode character is categorized as a symbol character.
	IsSymbol(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as a symbol character.
	IsUpper(Char)	Indicates whether the specified Unicode character is categorized as an uppercase letter.
	IsUpper(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as an uppercase letter.
	IsWhiteSpace(Char)	Indicates whether the specified Unicode character is categorized as white space.
	IsWhiteSpace(String, Int32)	Indicates whether the character at the specified position in a specified string is categorized as white space.
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ToLower(Char)	Converts the value of a Unicode character to its lowercase equivalent.
	ToLower(Char, CultureInfo)	Converts the value of a specified Unicode character to its lowercase equivalent using specified culture-specific formatting information.
	ToLowerInvariant	Converts the value of a Unicode character to its lowercase equivalent using the casing rules of the invariant culture.
	ToString()()()	Converts the value of this instance to its equivalent string representation. (Overrides ValueType..::.ToString()()().)
	ToString(Char)	Converts the specified Unicode character to its equivalent string representation.
	ToString(IFormatProvider)	Converts the value of this instance to its equivalent string representation using the specified culture-specific format information.
	ToUpper(Char)	Converts the value of a Unicode character to its uppercase equivalent.
	ToUpper(Char, CultureInfo)	Converts the value of a specified Unicode character to its uppercase equivalent using specified culture-specific formatting information.
	ToUpperInvariant	Converts the value of a Unicode character to its uppercase equivalent using the casing rules of the invariant culture.
	TryParse	Converts the value of the specified string to its equivalent Unicode character. A return code indicates whether the conversion succeeded or failed.

Top

Fields

	Name	Description
	MaxValue	Represents the largest possible value of a Char. This field is constant.
	MinValue	Represents the smallest possible value of a Char. This field is constant.

Top

Explicit Interface Implementations

	Name	Description
	IConvertible..::.ToBoolean	Infrastructure. Note   This conversion is not supported. Attempting to do so throws an InvalidCastException.
	IConvertible..::.ToByte	Infrastructure. For a description of this member, see ToByte.
	IConvertible..::.ToChar	Infrastructure. For a description of this member, see IConvertible..::.ToChar.
	IConvertible..::.ToDateTime	Infrastructure. Note   This conversion is not supported. Attempting to do so throws an InvalidCastException.
	IConvertible..::.ToDecimal	Infrastructure. Note   This conversion is not supported. Attempting to do so throws an InvalidCastException.
	IConvertible..::.ToDouble	Infrastructure. Note   This conversion is not supported. Attempting to do so throws an InvalidCastException.
	IConvertible..::.ToInt16	Infrastructure. For a description of this member, see ToInt16.
	IConvertible..::.ToInt32	Infrastructure. For a description of this member, see ToInt32.
	IConvertible..::.ToInt64	Infrastructure. For a description of this member, see ToInt64.
	IConvertible..::.ToSByte	Infrastructure. For a description of this member, see ToSByte.
	IConvertible..::.ToSingle	Infrastructure. Note   This conversion is not supported. Attempting to do so throws an InvalidCastException.
	IConvertible..::.ToType	Infrastructure. For a description of this member, see IConvertible..::.ToType.
	IConvertible..::.ToUInt16	Infrastructure. For a description of this member, see ToUInt16.
	IConvertible..::.ToUInt32	Infrastructure. For a description of this member, see ToUInt32.
	IConvertible..::.ToUInt64	Infrastructure. For a description of this member, see ToUInt64.

Top

Remarks

The .NET Framework uses the Char structure to represent a Unicode character. The Unicode Standard identifies each Unicode character with a unique 21-bit scalar number called a code point, and defines the UTF-16 encoding form that specifies how a code point is encoded into a sequence of one or more 16-bit values. Each 16-bit value ranges from hexadecimal 0x0000 through 0xFFFF and is stored in a Char structure. The value of a Char object is its 16-bit numeric (ordinal) value.

Char Objects, Unicode Characters, and Strings

A String object is a sequential collection of Char structures that represents a string of text. Most Unicode characters can be represented by a single Char object, but a character that is encoded as a base character, surrogate pair, and/or combining character sequence is represented by multiple Char objects. For this reason, a Char structure in a String object is not necessarily equivalent to a single Unicode character.

Multiple 16-bit code units are used to represent single Unicode characters in the following cases:

• Glyphs, which may consist of a single character or of a base character followed by one or more combining characters. For example, the character ä is represented by a Char object whose code unit is U+0061 followed by a Char object whose code unit is U+0308. (The character ä can also be defined by a single Char object that has a code unit of U+00E4.) The following example illustrates that the character ä consists of two Char objects.

  Module Example
     Public Sub Demo(outputBlock As System.Windows.Controls.TextBlock)
        Dim chars() As Char = {ChrW(&H61), ChrW(&H308)}
        Dim strng As New String(chars)
        outputBlock.Text += strng + vbCrLf
     End Sub
  End Module
  ' The example produces the following output:
  '       ä
  

  using System;
  
  public class Example
  {
     public static void Demo(System.Windows.Controls.TextBlock outputBlock)
     {
        char[] chars = { '\u0061', '\u0308' };
        string strng = new String(chars);
        outputBlock.Text += strng + Environment.NewLine;
     }
  }
  // The example produces the following output:
  //       ä
  

• Characters outside the Unicode Basic Multilingual Plane (BMP). Unicode supports sixteen planes in addition to the BMP, which represents plane 0. A Unicode code point is represented in UTF-32 by a 21-bit value that includes the plane. For example, U+1D160 represents the MUSICAL SYMBOL EIGHTH NOTE character. Because UTF-16 encoding has only 16 bits, characters outside the BMP are represented by surrogate pairs in UTF-16. For example, the UTF-16 equivalent of U+1D160, the MUSICAL SYMBOL EIGHTH NOTE character, is U+D834 U+DD60. U+D834 is the high surrogate; high surrogates range from U+D800 through U+DBFF. U+DD60 is the low surrogate; low surrogates range from U+DC00 through U+DFFF.

Because a single character can be represented by multiple Char objects, we recommend that you use strings instead of individual characters to represent and analyze linguistic content.

Characters and Text Elements

Because a single character can be represented by multiple Char objects, it is not always meaningful to work with individual Char objects. For instance, the following example converts the Unicode code points that represent the Aegean numbers zero through 9 to UTF-16 encoded code units. Because it erroneously equates Char objects with characters, it inaccurately reports that the resulting string has 20 characters.

You can do the following to avoid the assumption that a Char object represents a single character.

• You can work with a String object in its entirety instead of working with its individual characters to represent and analyze linguistic content.

• You can use the StringInfo class to work with text elements instead of individual Char objects. The following example uses the StringInfo object to count the number of text elements in a string that consists of the Aegean numbers zero through nine. Because it considers a surrogate pair a single character, it correctly reports that the string contains ten characters.

Functionality

The Char structure provides methods to compare Char objects, convert the value of the current Char object to an object of another type, and determine the Unicode category of a Char object:

• Use the CompareTo and Equals methods to compare Char objects.

• Use the GetUnicodeCategory methods to get the Unicode category of a character. Use the IsControl, IsDigit, IsLetter, IsLetterOrDigit, IsLower, IsNumber, IsPunctuation, IsSeparator, IsSurrogate, IsSurrogatePair, IsSymbol, IsUpper, and IsWhiteSpace methods to determine whether a character is in a particular Unicode category such as digit, letter, punctuation, control character, and so on.

• Use the GetNumericValue methods to convert a Char object that represents a number to a numeric value type. Use TryParse to convert a character in a string into a Char object. Use ToString to convert a Char object to a String object.

• Use the ToLower and ToUpper methods to change the case of a Char object.

Interface Implementations

This type implements the IConvertible, IComparable, and IComparable<(Of <(T>)>) interfaces. Use the Convert class for conversions instead of this type's explicit interface member implementation of IConvertible.

Examples

The following example demonstrates some of the methods in Char.

Module Example

   Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      Dim chA As Char = "A"c
      Dim ch1 As Char = "1"c
      Dim str As String = "test string"

      outputBlock.Text &= chA.CompareTo("B"c)                   ' Output: "-1" (meaning 'A' is 1 less than 'B' & vbCrLf
      outputBlock.Text &= chA.Equals("A"c) & vbCrLf             ' Output: "True"
      outputBlock.Text &= Char.GetNumericValue(ch1) & vbCrLf    ' Output: "1"
      outputBlock.Text &= Char.IsControl(ChrW(9)) & vbCrLf      ' Output: "True"
      outputBlock.Text &= Char.IsDigit(ch1) & vbCrLf            ' Output: "True"
      outputBlock.Text += Char.IsLetter(","c) & vbCrLf          ' Output: "False"
      outputBlock.Text &= Char.IsLower("u"c) & vbCrLf           ' Output: "True"
      outputBlock.Text &= Char.IsNumber(ch1) & vbCrLf           ' Output: "True"
      outputBlock.Text &= Char.IsPunctuation("."c) & vbCrLf     ' Output: "True"
      outputBlock.Text += Char.IsSeparator(str, 4) & vbCrLf     ' Output: "True"
      outputBlock.Text &= Char.IsSymbol("+"c) & vbCrLf          ' Output: "True"
      outputBlock.Text += Char.IsWhiteSpace(str, 4) & vbCrLf    ' Output: "True"
      outputBlock.Text &= Char.ToLower("M"c) & vbCrLf           ' Output: "m"
      outputBlock.Text &= "x"c.ToString() & vbCrLf              ' Output: "x"
   End Sub
End Module

using System;

public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      char chA = 'A';
      char ch1 = '1';
      string str = "test string";

      outputBlock.Text += chA.CompareTo('B') + "\n";            // Output: "-1" (meaning 'A' is 1 less than 'B')
      outputBlock.Text += chA.Equals('A') + "\n";               // Output: "True"
      outputBlock.Text += Char.GetNumericValue(ch1) + "\n"; // Output: "1"
      outputBlock.Text += Char.IsControl('\t') + "\n";      // Output: "True"
      outputBlock.Text += Char.IsDigit(ch1) + "\n";         // Output: "True"
      outputBlock.Text += Char.IsLetter(',') + "\n";            // Output: "False"
      outputBlock.Text += Char.IsLower('u') + "\n";         // Output: "True"
      outputBlock.Text += Char.IsNumber(ch1) + "\n";            // Output: "True"
      outputBlock.Text += Char.IsPunctuation('.') + "\n";   // Output: "True"
      outputBlock.Text += Char.IsSeparator(str, 4) + "\n";  // Output: "True"
      outputBlock.Text += Char.IsSymbol('+') + "\n";            // Output: "True"
      outputBlock.Text += Char.IsWhiteSpace(str, 4) + "\n"; // Output: "True"
      outputBlock.Text += Char.ToLower('M') + "\n";         // Output: "m"
      outputBlock.Text += 'x'.ToString() + "\n";                // Output: "x"
   }
}

Version Information

Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Platforms

Windows Phone

Thread Safety

All members of this type are thread safe. Members that appear to modify instance state actually return a new instance initialized with the new value. As with any other type, reading and writing to a shared variable that contains an instance of this type must be protected by a lock to guarantee thread safety.

See Also

Reference

System Namespace

IComparable

IConvertible

String