BitConverter Class

Definition

Namespace:

System

Assembly:

System.Runtime.dll

Source:

BitConverter.cs

Converts base data types to an array of bytes, and an array of bytes to base data types.

public ref class BitConverter abstract sealed

public static class BitConverter

type BitConverter = class

Public Class BitConverter

Inheritance

Object

BitConverter

Examples

The following code example illustrates the use of several BitConverter class methods.

// Example of BitConverter class methods.
using namespace System;
int main()
{
   String^ formatter = "{0,25}{1,30}";
   double aDoubl = 0.1111111111111111111;
   float aSingl = 0.1111111111111111111F;
   __int64 aLong = 1111111111111111111;
   int anInt = 1111111111;
   short aShort = 11111;
   __wchar_t aChar = L'*';
   bool aBool = true;
   Console::WriteLine( "This example of methods of the BitConverter class"
   "\ngenerates the following output.\n" );
   Console::WriteLine( formatter, "argument", "byte array" );
   Console::WriteLine( formatter, "--------", "----------" );
   
   // Convert values to Byte arrays and display them.
   Console::WriteLine( formatter, aDoubl, BitConverter::ToString( BitConverter::GetBytes( aDoubl ) ) );
   Console::WriteLine( formatter, aSingl, BitConverter::ToString( BitConverter::GetBytes( aSingl ) ) );
   Console::WriteLine( formatter, aLong, BitConverter::ToString( BitConverter::GetBytes( aLong ) ) );
   Console::WriteLine( formatter, anInt, BitConverter::ToString( BitConverter::GetBytes( anInt ) ) );
   Console::WriteLine( formatter, aShort, BitConverter::ToString( BitConverter::GetBytes( aShort ) ) );
   Console::WriteLine( formatter, aChar, BitConverter::ToString( BitConverter::GetBytes( aChar ) ) );
   Console::WriteLine( formatter, aBool, BitConverter::ToString( BitConverter::GetBytes( aBool ) ) );
}

/*
This example of methods of the BitConverter class
generates the following output.

                 argument                    byte array
                 --------                    ----------
        0.111111111111111       1C-C7-71-1C-C7-71-BC-3F
                0.1111111                   39-8E-E3-3D
      1111111111111111111       C7-71-C4-2B-AB-75-6B-0F
               1111111111                   C7-35-3A-42
                    11111                         67-2B
                        *                         2A-00
                     True                            01
*/

// Example of BitConverter class methods.
using System;

class BitConverterDemo
{
    public static void Main( )
    {
        const string formatter = "{0,25}{1,30}";

        double  aDoubl  = 0.1111111111111111111;
        float   aSingl  = 0.1111111111111111111F;
        long    aLong   = 1111111111111111111;
        int     anInt   = 1111111111;
        short   aShort  = 11111;
        char    aChar   = '*';
        bool    aBool   = true;

        Console.WriteLine(
            "This example of methods of the BitConverter class" +
            "\ngenerates the following output.\n" );
        Console.WriteLine( formatter, "argument", "byte array" );
        Console.WriteLine( formatter, "--------", "----------" );

        // Convert values to Byte arrays and display them.
        Console.WriteLine( formatter, aDoubl,
            BitConverter.ToString( BitConverter.GetBytes( aDoubl ) ) );
        Console.WriteLine( formatter, aSingl,
            BitConverter.ToString( BitConverter.GetBytes( aSingl ) ) );
        Console.WriteLine( formatter, aLong,
            BitConverter.ToString( BitConverter.GetBytes( aLong ) ) );
        Console.WriteLine( formatter, anInt,
            BitConverter.ToString( BitConverter.GetBytes( anInt ) ) );
        Console.WriteLine( formatter, aShort,
            BitConverter.ToString( BitConverter.GetBytes( aShort ) ) );
        Console.WriteLine( formatter, aChar,
            BitConverter.ToString( BitConverter.GetBytes( aChar ) ) );
        Console.WriteLine( formatter, aBool,
            BitConverter.ToString( BitConverter.GetBytes( aBool ) ) );
    }
}

/*
This example of methods of the BitConverter class
generates the following output.

                 argument                    byte array
                 --------                    ----------
        0.111111111111111       1C-C7-71-1C-C7-71-BC-3F
                0.1111111                   39-8E-E3-3D
      1111111111111111111       C7-71-C4-2B-AB-75-6B-0F
               1111111111                   C7-35-3A-42
                    11111                         67-2B
                        *                         2A-00
                     True                            01
*/

open System

let print: obj -> obj -> unit = printfn "%25O%30O"

let aDoubl = 0.1111111111111111111
let aSingl = 0.1111111111111111111f
let aLong = 1111111111111111111L
let anInt = 1111111111
let aShort = 11111s
let aChar = '*'
let aBool = true

printfn "This example of methods of the BitConverter class\ngenerates the following output.\n"
print "argument" "byte array"
print "--------" "----------"

// Convert values to Byte arrays and display them.
print aDoubl (BitConverter.ToString(BitConverter.GetBytes aDoubl))

print aSingl (BitConverter.ToString(BitConverter.GetBytes aSingl))

print aLong (BitConverter.ToString(BitConverter.GetBytes aLong))

print anInt (BitConverter.ToString(BitConverter.GetBytes anInt))

print aShort (BitConverter.ToString(BitConverter.GetBytes aShort))

print aChar (BitConverter.ToString(BitConverter.GetBytes aChar))

print aBool (BitConverter.ToString(BitConverter.GetBytes aBool))


// This example of methods of the BitConverter class
// generates the following output.
//
//                  argument                    byte array
//                  --------                    ----------
//         0.111111111111111       1C-C7-71-1C-C7-71-BC-3F
//                 0.1111111                   39-8E-E3-3D
//       1111111111111111111       C7-71-C4-2B-AB-75-6B-0F
//                1111111111                   C7-35-3A-42
//                     11111                         67-2B
//                         *                         2A-00
//                      True                            01

' Example of BitConverter class methods.
Module BitConverterDemo

    Sub Main( )

        Const formatter As String = "{0,25}{1,30}"
 
        Dim aDoubl      As Double   = 0.1111111111111111111
        Dim aSingl      As Single   = 0.1111111111111111111
        Dim aLong       As Long     = 1111111111111111111
        Dim anInt       As Integer  = 1111111111
        Dim aShort      As Short    = 11111
        Dim aChar       As Char     = "*"c
        Dim aBool       As Boolean  = True

        Console.WriteLine( _
            "This example of methods of the BitConverter class" & _
            vbCrLf & "generates the following output." & vbCrLf )
        Console.WriteLine( formatter, "argument", "Byte array" )
        Console.WriteLine( formatter, "--------", "----------" )

        ' Convert values to Byte arrays and display them.
        Console.WriteLine( formatter, aDoubl, _
            BitConverter.ToString( BitConverter.GetBytes( aDoubl ) ) )
        Console.WriteLine( formatter, aSingl, _
            BitConverter.ToString( BitConverter.GetBytes( aSingl ) ) )
        Console.WriteLine( formatter, aLong, _
            BitConverter.ToString( BitConverter.GetBytes( aLong ) ) )
        Console.WriteLine( formatter, anInt, _
            BitConverter.ToString( BitConverter.GetBytes( anInt ) ) )
        Console.WriteLine( formatter, aShort, _
            BitConverter.ToString( BitConverter.GetBytes( aShort ) ) )
        Console.WriteLine( formatter, aChar, _
            BitConverter.ToString( BitConverter.GetBytes( aChar ) ) )
        Console.WriteLine( formatter, aBool, _
            BitConverter.ToString( BitConverter.GetBytes( aBool ) ) )
    End Sub
End Module

' This example of methods of the BitConverter class
' generates the following output.
' 
'                  argument                    Byte array
'                  --------                    ----------
'         0.111111111111111       1C-C7-71-1C-C7-71-BC-3F
'                 0.1111111                   39-8E-E3-3D
'       1111111111111111111       C7-71-C4-2B-AB-75-6B-0F
'                1111111111                   C7-35-3A-42
'                     11111                         67-2B
'                         *                         2A-00
'                      True                            01

Remarks

The BitConverter class helps manipulate value types in their fundamental form, as a series of bytes. A byte is defined as an 8-bit unsigned integer. The BitConverter class includes static methods to convert each of the primitive types to and from an array of bytes, as the following table illustrates.

Type	To byte conversion	From byte conversion
Boolean	GetBytes(Boolean)	ToBoolean
Char	GetBytes(Char)	ToChar
Double	GetBytes(Double) -or- DoubleToInt64Bits(Double) -or- DoubleToUInt64Bits(Double)	ToDouble -or- Int64BitsToDouble -or- UInt64BitsToDouble
Half	GetBytes(Half) -or- HalfToInt16Bits(Half) -or- HalfToUInt16Bits(Half)	ToHalf -or- Int16BitsToHalf -or- UInt16BitsToHalf
Int16	GetBytes(Int16)	ToInt16
Int32	GetBytes(Int32)	ToInt32
Int64	GetBytes(Int64)	ToInt64
Single	GetBytes(Single) -or- SingleToInt32Bits(Single) -or- SingleToUInt32Bits(Single)	ToSingle -or- Int32BitsToSingle -or- UInt32BitsToSingle
UInt16	GetBytes(UInt16)	ToUInt16
UInt32	GetBytes(UInt32)	ToUInt32
UInt64	GetBytes(UInt64)	ToUInt64

If you use BitConverter methods to round-trip data, make sure that the GetBytes overload and the ToType method specify the same type. As the following example illustrates, restoring an array that represents a signed integer by calling the ToUInt32 method can result in a value that is different from the original. For more information, see Working with Signed Non-Decimal and Bitwise Values.

using System;

public class Example
{
   public static void Main()
   {
      int value = -16;
      Byte[] bytes = BitConverter.GetBytes(value);

      // Convert bytes back to int.
      int intValue = BitConverter.ToInt32(bytes, 0);
      Console.WriteLine("{0} = {1}: {2}",
                        value, intValue,
                        value.Equals(intValue) ? "Round-trips" : "Does not round-trip");
      // Convert bytes to UInt32.
      uint uintValue = BitConverter.ToUInt32(bytes, 0);
      Console.WriteLine("{0} = {1}: {2}", value, uintValue,
                        value.Equals(uintValue) ? "Round-trips" : "Does not round-trip");
   }
}
// The example displays the following output:
//       -16 = -16: Round-trips
//       -16 = 4294967280: Does not round-trip

open System

let value = -16
let bytes = BitConverter.GetBytes value

// Convert bytes back to int.
let intValue = BitConverter.ToInt32(bytes, 0)
printfn $"""{value} = {intValue}: {if value.Equals intValue then "Round-trips" else "Does not round-trip"}"""

// Convert bytes to UInt32.
let uintValue = BitConverter.ToUInt32(bytes, 0)
printfn $"""{value} = {uintValue}: {if value.Equals uintValue then "Round-trips" else "Does not round-trip"}"""


// The example displays the following output:
//       -16 = -16: Round-trips
//       -16 = 4294967280: Does not round-trip

Module Example
   Public Sub Main()
      Dim value As Integer = -16
      Dim bytes() As Byte = BitConverter.GetBytes(value) 
      
      ' Convert bytes back to Int32.
      Dim intValue As Integer = BitConverter.ToInt32(bytes, 0)
      Console.WriteLine("{0} = {1}: {2}", 
                        value, intValue, 
                        If(value.Equals(intValue), "Round-trips", "Does not round-trip"))
      ' Convert bytes to UInt32.
      Dim uintValue As UInteger = BitConverter.ToUInt32(bytes, 0)
      Console.WriteLine("{0} = {1}: {2}", value, uintValue, 
                        If(value.Equals(uintValue), "Round-trips", "Does not round-trip"))
   End Sub
End Module
' The example displays the following output:
'       -16 = -16: Round-trips
'       -16 = 4294967280: Does not round-trip

The order of bytes in the array returned by the GetBytes method overloads (as well as the order of bits in the integer returned by the DoubleToInt64Bits method) depends on whether the computer architecture is little-endian or big-endian. Similarly, the order of bytes in the array and returned by the ToIntegerValue methods and the ToChar method depends on whether the computer architecture is little-endian or big-endian. The endianness of an architecture is indicated by the IsLittleEndian property, which returns true on little-endian systems and false on big-endian systems. On little-endian systems, lower-order bytes precede higher-order bytes. On big-endian system, higher-order bytes precede lower-order bytes. The following table illustrates the difference in the byte arrays that result from passing the integer 1,234,567,890 (0x499602D2) to the GetBytes(Int32) method. The bytes are listed in order from the byte at index 0 to the byte at index 3.

Little-endian	D2-02-96-49
Big-endian	49-96-02-D2

Because the return value of some methods depends on system architecture, be careful when transmitting byte data beyond machine boundaries:

• If all systems sending and receiving data are guaranteed to have the same endianness, nothing has to be done to the data.

• If systems sending and receiving data can have different endianness, always transmit data in a particular order. This means that the order of bytes in the array may have to be reversed either before sending them or after receiving them. A common convention is to transmit data in network byte order (big-endian order). The following example provides an implementation for sending an integer value in network byte order.

  using System;
  
  public class Example
  {
     public static void Main()
     {
        int value = 12345678;
        byte[] bytes = BitConverter.GetBytes(value);
        Console.WriteLine(BitConverter.ToString(bytes));
  
        if (BitConverter.IsLittleEndian)
           Array.Reverse(bytes);
  
        Console.WriteLine(BitConverter.ToString(bytes));
        // Call method to send byte stream across machine boundaries.
  
        // Receive byte stream from beyond machine boundaries.
        Console.WriteLine(BitConverter.ToString(bytes));
        if (BitConverter.IsLittleEndian)
           Array.Reverse(bytes);
  
        Console.WriteLine(BitConverter.ToString(bytes));
        int result = BitConverter.ToInt32(bytes, 0);
        Console.WriteLine("Original value: {0}", value);
        Console.WriteLine("Returned value: {0}", result);
     }
  }
  // The example displays the following output on a little-endian system:
  //       4E-61-BC-00
  //       00-BC-61-4E
  //       00-BC-61-4E
  //       4E-61-BC-00
  //       Original value: 12345678
  //       Returned value: 12345678
  

  open System
  
  let value = 12345678
  let bytes = BitConverter.GetBytes value
  printfn $"{BitConverter.ToString bytes}"
  
  if BitConverter.IsLittleEndian then
      Array.Reverse bytes
  
  printfn $"{BitConverter.ToString bytes}"
  // Call method to send byte stream across machine boundaries.
  
  // Receive byte stream from beyond machine boundaries.
  printfn $"{BitConverter.ToString bytes}"
  if BitConverter.IsLittleEndian then
      Array.Reverse bytes
  
  printfn $"{BitConverter.ToString bytes}"
  let result = BitConverter.ToInt32(bytes, 0)
  
  printfn $"Original value: {value}"
  printfn $"Returned value: {result}"
  
  // The example displays the following output on a little-endian system:
  //       4E-61-BC-00
  //       00-BC-61-4E
  //       00-BC-61-4E
  //       4E-61-BC-00
  //       Original value: 12345678
  //       Returned value: 12345678
  

  Module Example
     Public Sub Main()
        Dim value As Integer = 12345678
        Dim bytes() As Byte = BitConverter.GetBytes(value)
        Console.WriteLine(BitConverter.ToString(bytes))
        
        If BitConverter.IsLittleEndian Then
           Array.Reverse(bytes) 
        End If
        Console.WriteLine(BitConverter.ToString(bytes))
        ' Call method to send byte stream across machine boundaries.
        
        ' Receive byte stream from beyond machine boundaries.
        Console.WriteLine(BitConverter.ToString(bytes))
        If BitConverter.IsLittleEndian Then     
           Array.Reverse(bytes)
        End If   
        Console.WriteLine(BitConverter.ToString(bytes))
        Dim result As Integer = BitConverter.ToInt32(bytes, 0)
        Console.WriteLine("Original value: {0}", value)
        Console.WriteLine("Returned value: {0}", result)
     End Sub
  End Module
  ' The example displays the following output on a little-endian system:
  '       4E-61-BC-00
  '       00-BC-61-4E
  '       00-BC-61-4E
  '       4E-61-BC-00
  '       Original value: 12345678
  '       Returned value: 12345678
  

• If systems sending and receiving data can have different endianness and the data to be transmitted consists of signed integers, call the IPAddress.HostToNetworkOrder method to convert the data to network byte order and the IPAddress.NetworkToHostOrder method to convert it to the order required by the recipient.

Fields

IsLittleEndian

Indicates the byte order ("endianness") in which data is stored in this computer architecture.

Methods

DoubleToInt64Bits(Double)	Converts the specified double-precision floating point number to a 64-bit signed integer.
DoubleToUInt64Bits(Double)	Converts the specified double-precision floating point number to a 64-bit unsigned integer.
GetBytes(Boolean)	Returns the specified Boolean value as a byte array.
GetBytes(Char)	Returns the specified Unicode character value as an array of bytes.
GetBytes(Double)	Returns the specified double-precision floating-point value as an array of bytes.
GetBytes(Half)	Returns the specified half-precision floating-point value as an array of bytes.
GetBytes(Int16)	Returns the specified 16-bit signed integer value as an array of bytes.
GetBytes(Int32)	Returns the specified 32-bit signed integer value as an array of bytes.
GetBytes(Int64)	Returns the specified 64-bit signed integer value as an array of bytes.
GetBytes(Single)	Returns the specified single-precision floating point value as an array of bytes.
GetBytes(UInt16)	Returns the specified 16-bit unsigned integer value as an array of bytes.
GetBytes(UInt32)	Returns the specified 32-bit unsigned integer value as an array of bytes.
GetBytes(UInt64)	Returns the specified 64-bit unsigned integer value as an array of bytes.
HalfToInt16Bits(Half)	Converts a half-precision floating-point value into a 16-bit integer.
HalfToUInt16Bits(Half)	Converts the specified half-precision floating point number to a 16-bit unsigned integer.
Int16BitsToHalf(Int16)	Reinterprets the specified 16-bit signed integer value as a half-precision floating-point value.
Int32BitsToSingle(Int32)	Reinterprets the specified 32-bit integer as a single-precision floating-point value.
Int64BitsToDouble(Int64)	Reinterprets the specified 64-bit signed integer to a double-precision floating point number.
SingleToInt32Bits(Single)	Converts a single-precision floating-point value into an integer.
SingleToUInt32Bits(Single)	Converts the specified single-precision floating point number to a 32-bit unsigned integer.
ToBoolean(Byte[], Int32)	Returns a Boolean value converted from the byte at a specified position in a byte array.
ToBoolean(ReadOnlySpan<Byte>)	Converts a read-only byte span to a Boolean value.
ToChar(Byte[], Int32)	Returns a Unicode character converted from two bytes at a specified position in a byte array.
ToChar(ReadOnlySpan<Byte>)	Converts a read-only byte span into a character.
ToDouble(Byte[], Int32)	Returns a double-precision floating point number converted from eight bytes at a specified position in a byte array.
ToDouble(ReadOnlySpan<Byte>)	Converts a read-only byte span into a double-precision floating-point value.
ToHalf(Byte[], Int32)	Returns a half-precision floating point number converted from two bytes at a specified position in a byte array.
ToHalf(ReadOnlySpan<Byte>)	Converts a read-only byte span into a half-precision floating-point value.
ToInt16(Byte[], Int32)	Returns a 16-bit signed integer converted from two bytes at a specified position in a byte array.
ToInt16(ReadOnlySpan<Byte>)	Converts a read-only byte span into a 16-bit signed integer.
ToInt32(Byte[], Int32)	Returns a 32-bit signed integer converted from four bytes at a specified position in a byte array.
ToInt32(ReadOnlySpan<Byte>)	Converts a read-only byte span into a 32-bit signed integer.
ToInt64(Byte[], Int32)	Returns a 64-bit signed integer converted from eight bytes at a specified position in a byte array.
ToInt64(ReadOnlySpan<Byte>)	Converts a read-only byte span into a 64-bit signed integer.
ToSingle(Byte[], Int32)	Returns a single-precision floating point number converted from four bytes at a specified position in a byte array.
ToSingle(ReadOnlySpan<Byte>)	Converts a read-only byte span into a single-precision floating-point value.
ToString(Byte[], Int32, Int32)	Converts the numeric value of each element of a specified subarray of bytes to its equivalent hexadecimal string representation.
ToString(Byte[], Int32)	Converts the numeric value of each element of a specified subarray of bytes to its equivalent hexadecimal string representation.
ToString(Byte[])	Converts the numeric value of each element of a specified array of bytes to its equivalent hexadecimal string representation.
ToUInt16(Byte[], Int32)	Returns a 16-bit unsigned integer converted from two bytes at a specified position in a byte array.
ToUInt16(ReadOnlySpan<Byte>)	Converts a read-only byte-span into a 16-bit unsigned integer.
ToUInt32(Byte[], Int32)	Returns a 32-bit unsigned integer converted from four bytes at a specified position in a byte array.
ToUInt32(ReadOnlySpan<Byte>)	Converts a read-only byte span into a 32-bit unsigned integer.
ToUInt64(Byte[], Int32)	Returns a 64-bit unsigned integer converted from eight bytes at a specified position in a byte array.
ToUInt64(ReadOnlySpan<Byte>)	Converts bytes into an unsigned long.
TryWriteBytes(Span<Byte>, Boolean)	Converts a Boolean into a span of bytes.
TryWriteBytes(Span<Byte>, Char)	Converts a character into a span of bytes.
TryWriteBytes(Span<Byte>, Double)	Converts a double-precision floating-point value into a span of bytes.
TryWriteBytes(Span<Byte>, Half)	Converts a half-precision floating-point value into a span of bytes.
TryWriteBytes(Span<Byte>, Int16)	Converts a 16-bit signed integer into a span of bytes.
TryWriteBytes(Span<Byte>, Int32)	Converts a 32-bit signed integer into a span of bytes.
TryWriteBytes(Span<Byte>, Int64)	Converts a 64-bit signed integer into a span of bytes.
TryWriteBytes(Span<Byte>, Single)	Converts a single-precision floating-point value into a span of bytes.
TryWriteBytes(Span<Byte>, UInt16)	Converts an unsigned 16-bit integer into a span of bytes.
TryWriteBytes(Span<Byte>, UInt32)	Converts a 32-bit unsigned integer into a span of bytes.
TryWriteBytes(Span<Byte>, UInt64)	Converts an unsigned 64-bit integer into a span of bytes.
UInt16BitsToHalf(UInt16)	Converts the specified 16-bit unsigned integer to a half-precision floating point number.
UInt32BitsToSingle(UInt32)	Converts the specified 32-bit unsigned integer to a single-precision floating point number.
UInt64BitsToDouble(UInt64)	Converts the specified 64-bit unsigned integer to a double-precision floating point number.

See also

• Byte