Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Numbers and Math

C# Convert class

Reference for the C# Convert class: convert between numbers, strings, bools, bytes and base-2/8/16, with rounding, null and overflow rules explained.

System.Convert is a static class with methods that convert between the base types: numbers, bool, char, string, DateTime, byte[] and more. Its method names follow the pattern ToXxx (ToInt32, ToDouble, ToString, ToBoolean) and each is overloaded for every source type.

Three behaviors set Convert apart from casts and from Parse. Converting a floating-point number to an integer rounds to the nearest value (ties go to even) instead of truncating. Converting null to a number or bool gives 0 or false instead of throwing. And out-of-range values always throw OverflowException, regardless of any unchecked context.

C#
int a = Convert.ToInt32(2.5);    // 2 (banker's rounding)
int b = (int)2.9;                // 2 (a cast truncates)
int c = Convert.ToInt32("42");   // 42 (parses the string)

Try it

C# Rounding, parsing and null

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Bases, bytes and ChangeType

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public static int     Convert.ToInt32(double value)          // also string, bool, char, decimal, long, object ...
public static int     Convert.ToInt32(string? value, int fromBase)
public static double  Convert.ToDouble(string? value, IFormatProvider? provider)
public static bool    Convert.ToBoolean(string? value)
public static string  Convert.ToString(int value, int toBase)
public static object  Convert.ChangeType(object? value, Type conversionType, IFormatProvider? provider)
public static string  Convert.ToBase64String(byte[] inArray)
public static byte[]  Convert.FromBase64String(string s)
public static string  Convert.ToHexString(byte[] inArray)
public static byte[]  Convert.FromHexString(string s)
Name Description
value The value to convert. null is accepted for most string and object overloads.
fromBase / toBase The number base: 2, 8, 10 or 16. Anything else throws ArgumentException.
provider Supplies culture rules for text. Pass CultureInfo.InvariantCulture for culture-neutral data.
conversionType The target type for ChangeType.

Returns: the converted value in the requested type.

Errors: FormatException when text is not a valid number or bool (and for an empty string), OverflowException when the result does not fit, InvalidCastException when no conversion exists (for example Convert.ToInt32(DateTime.Now)), ArgumentNullException for Convert.FromBase64String(null).

Usage notes

  • Rounding differs from a cast. Convert.ToInt32(2.5) is 2 because ties round to the nearest even number; (int)2.5 truncates and also gives 2, but 3.5 converts to 4 with Convert and 3 with a cast. Use Math.Round with an explicit mode when the rule matters.
  • null is forgiving, empty is not. Convert.ToInt32((string?)null) returns 0, but Convert.ToInt32("") throws FormatException.
  • Prefer TryParse for user input. Convert.ToInt32("abc") throws, and exceptions are slow when failures are common. Use int.TryParse for text that may be wrong.
  • Overflow always throws. Convert checks ranges even inside unchecked code, unlike a cast.
  • Cultures. The overloads without a provider use the current culture. The runner here uses the invariant culture, but on a real machine the same call can read 1,5 differently. Pass a provider for stored or transmitted data.
  • Hex and Base64. ToHexString, FromHexString (.NET 5+) and ToBase64String are the standard way to show bytes as text. FromHexString is case-insensitive.
  • Boxing. The object overloads and ChangeType box value types. Use the typed overloads in hot paths.
  • Convert.ToChar(int) converts a code unit; it does not handle characters above U+FFFF.