System.Single Structure

Summary

Represents a single-precision floating point number.

C# Syntax:

[Serializable] public struct Single : IComparable, IFormattable, IConvertible

The Single value type represents a single-precision 32-bit number with values ranging from negative 3.402823e38 to positive 3.402823e38, as well as positive or negative zero, Single.PositiveInfinity, Single.NegativeInfinity, and not a number ( Single.NaN).

Single complies with the IEC 60559:1989 (IEEE 754) standard for binary floating-point arithmetic.

Single provides methods to compare instances of this type, convert the value of an instance to its string representation, and convert the string representation of a number to an instance of this type.

For information about how format specification codes control the string representation of value types, see the conceptual topic at MSDN: formattingoverview.

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

When performing binary operations, if one of the operands is a floating-point type, Single or Double, then the other operand is required to be an integral type or a floating-point type. The operation is evaluated as follows:

• If one of the operands is of an integral type, then that operand is converted to the floating-point type of the other operand.
• Then, if either of the operands is Double, the other operand is converted to Double, and the operation is performed using at least the range and precision of the Double. For numeric operations, the type of the result is Double.
• Otherwise, the operation is performed using at least the range and precision of the Single type and, for numeric operations, the type of the result is Single.

The floating-point operators, including the assignment operators, do not throw exceptions. Instead, in exceptional situations, the result of a floating-point operation is zero, infinity, or NaN, as described below:

• If the result of a floating-point operation is too small for the destination format, the result of the operation is zero.
• If the magnitude of the result of a floating-point operation is too large for the destination format, the result of the operation is Single.PositiveInfinity or Single.NegativeInfinity, as appropriate for the sign of the result.
• If a floating-point operation is invalid, the result of the operation is Single.NaN.
• If one or both operands of a floating-point operation are Single.NaN, the result of the operation is Single.NaN.

System Namespace

System.Single Member List:

Public Fields

Epsilon	Represents the smallest positive Single greater than zero. This field is constant.
MaxValue	Represents the largest possible value of Single. This field is constant.
MinValue	Represents the smallest possible value of Single. This field is constant.
NaN	Represents not a number (NaN). This field is constant.
NegativeInfinity	Represents negative infinity. This field is constant.
PositiveInfinity	Represents positive infinity. This field is constant.

Public Methods

CompareTo	Compares this instance to a specified object and returns an indication of their relative values.
Equals	Overridden: Returns a value indicating whether this instance is equal to a specified object.
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 value type Single.
IsInfinity	Returns a value indicating whether the specified number evaluates to negative or positive infinity.
IsNaN	Returns a value indicating whether the specified number evaluates to not a number ( Single.NaN).
IsNegativeInfinity	Returns a value indicating whether the specified number evaluates to negative infinity.
IsPositiveInfinity	Returns a value indicating whether the specified number evaluates to positive infinity.
Parse	Overloaded: Parse(string s) Converts the string representation of a number to its single-precision floating point number equivalent.
Parse	Overloaded: Parse(string s, IFormatProvider provider) Converts the string representation of a number in a specified culture-specific format to its single-precision floating point number equivalent.
Parse	Overloaded: Parse(string s, NumberStyles style) Converts the string representation of a number in a specified style to its single-precision floating point number equivalent.
Parse	Overloaded: Parse(string s, NumberStyles style, IFormatProvider provider) Converts the string representation of a number in a specified style and culture-specific format to its single-precision floating point number equivalent.
ToString	Overloaded: ToString() Overridden: Converts the numeric value of this instance to its equivalent string representation.
ToString	Overloaded: ToString(IFormatProvider provider) Converts the numeric value of this instance to its equivalent string representation using the specified culture-specific format information.
ToString	Overloaded: ToString(string format) Converts the numeric value of this instance to its equivalent string representation, using the specified format.
ToString	Overloaded: ToString(string format, IFormatProvider provider) Converts the numeric value of this instance to its equivalent string representation using the specified format and culture-specific format information.

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.Object
• System.ValueType
• System.Single

System.Single Member Details

Summary

Represents the smallest positive Single greater than zero. This field is constant.

C# Syntax:

public const float Epsilon;

The value of this constant is 1.4e-45.

Two apparently equivalent floating point numbers might not compare equal because of differences in their least significant digits. For example, the C# expression, (float)1/3 == (float)0.33333 , does not compare equal because the division operation on the left-hand side has maximum precision while the constant on the right-hand side is only precise to the visible digits.

Instead, determine if the two sides of a comparison are close enough to equal for your purposes by comparing whether the absolute value of the difference between the left and right-hand sides is less than Epsilon.

Return to top

Summary

Represents the largest possible value of Single. This field is constant.

C# Syntax:

public const float MaxValue;

The value of this constant is positive 3.402823e38.

Return to top

Summary

Represents the smallest possible value of Single. This field is constant.

C# Syntax:

public const float MinValue;

The value of this constant is negative 3.402823e38.

Return to top

Summary

Represents not a number (NaN). This field is constant.

C# Syntax:

public const float NaN;

The value of this constant is the result of dividing zero by zero.

This constant is returned when the result of an operation is undefined.

Use Single.IsNaN to determine whether a value is not a number. It is not possible to determine whether a value is not a number by comparing it to another value equal to NaN.

Return to top

Summary

Represents negative infinity. This field is constant.

C# Syntax:

public const float NegativeInfinity;

The value of this constant is the result of dividing a negative number by zero.

This constant is returned when the result of an operation is less than Single.MinValue.

Use Single.IsNegativeInfinity to determine whether a value evaluates to negative infinity. It is not possible to determine whether a value evaluates to negative infinity by comparing it to another value equal to NegativeInfinity.

Return to top

Summary

Represents positive infinity. This field is constant.

C# Syntax:

public const float PositiveInfinity;

The value of this constant is the result of dividing a positive number by zero.

This constant is returned when the result of an operation is greater than Single.MaxValue.

Use Single.IsPositiveInfinity to determine whether a value evaluates to positive infinity. It is not possible to determine whether a value evaluates to positive infinity by comparing it to another value equal to PositiveInfinity.

Return to top

Summary

Compares this instance to a specified object and returns an indication of their relative values.

C# Syntax:

public int CompareTo(    object value );

value

An object to compare, or null.

Return Value:

A signed number indicating the relative values of this instance and value.

Return Value	Description
Less than zero	This instance is less than value. -or- This instance is not a number ( Single.NaN) and value is a number.
Zero	This instance is equal to value. -or- This instance and value are both not a number ( Single.NaN), Single.PositiveInfinity, or Single.NegativeInfinity.
Greater than zero	This instance is greater than value. -or- This instance is a number and value is not a number ( Single.NaN). -or- value is null.

Exceptions

Exception Type	Condition
ArgumentException	value is not a Single or null.

Any instance of Single, regardless of its value, is considered greater than null.

The value parameter must be null or an instance of Single; otherwise, an exception is thrown.

This method is implemented to support the IComparable interface. Note that, although a Single.NaN is not considered to be equal to another Single.NaN (even itself), the IComparable interface requires that A.CompareTo(A) return zero.

Return to top

Summary

Returns a value indicating whether this instance is equal to a specified object.

C# Syntax:

public override bool Equals(    object obj );

obj

An object to compare with this instance.

Return Value:

true if obj is an instance of Single and equals the value of this instance; otherwise, false.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~Single();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the hash code for this instance.

C# Syntax:

public override int GetHashCode();

Return Value:

A 32-bit signed integer hash code.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the TypeCode for value type Single.

C# Syntax:

public TypeCode GetTypeCode();

Return Value:

The enumerated constant, TypeCode.Single.

Return to top

Summary

Returns a value indicating whether the specified number evaluates to negative or positive infinity.

C# Syntax:

public static bool IsInfinity(    float f );

f

A single-precision floating point number.

Return Value:

true if f evaluates to Single.PositiveInfinity or Single.NegativeInfinity; otherwise, false.

Floating-point operations return Single.PositiveInfinity or Single.NegativeInfinity to signal an overflow condition.

Return to top

Summary

Returns a value indicating whether the specified number evaluates to not a number ( Single.NaN).

C# Syntax:

public static bool IsNaN(    float f );

f

A single-precision floating point number.

Return Value:

true if f evaluates to not a number ( Single.NaN); otherwise, false.

Floating-point operations return Single.NaN to signal that that result of the operation is undefined. For example, dividing 0.0 by 0.0 results in Single.NaN.

Return to top

Summary

Returns a value indicating whether the specified number evaluates to negative infinity.

C# Syntax:

public static bool IsNegativeInfinity(    float f );

f

A single-precision floating point number.

Return Value:

true if f evaluates to Single.NegativeInfinity; otherwise, false.

Floating-point operations return Single.NegativeInfinity to signal an overflow condition.

Return to top

Summary

Returns a value indicating whether the specified number evaluates to positive infinity.

C# Syntax:

public static bool IsPositiveInfinity(    float f );

f

A single-precision floating point number.

Return Value:

true if f evaluates to Single.PositiveInfinity; otherwise, false.

Floating-point operations return Single.PositiveInfinity to signal an overflow condition.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Converts the string representation of a number to its single-precision floating point number equivalent.

C# Syntax:

public static float Parse(    string s );

s

A string representing a number to convert.

Return Value:

A single-precision floating point number equivalent to the numeric value or symbol specified in s.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.
FormatException	s is not a number in a valid format.
OverflowException	s represents a number less than Single.MinValue or greater than Single.MaxValue.

The s parameter can contain NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[ws][sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits][ws]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

ws A series of white space characters. sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Runs of integral-digits can be partitioned by a group-separator symbol. (For example, in some cultures a comma (,) separates groups of thousands.) Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' An uppercase or lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of s are "100", "-123,456,789", "123.45+e6", "+500", "5e2", "3.1416", "600.", "-.123", and "-Infinity".

This version of Parse uses the NumberStyles values, NumberStyles.Float and NumberStyles.AllowThousands, and the culture-specific NumberFormatInfo data associated with the current thread.

For more information about numeric formats, see the the conceptual topic at MSDN: formattingoverview topic.

Return to top

Summary

Converts the string representation of a number in a specified culture-specific format to its single-precision floating point number equivalent.

C# Syntax:

public static float Parse(    string s,    IFormatProvider provider );

s

A string representing a number to convert.

provider

An IFormatProvider that supplies culture-specific formatting information about s.

Return Value:

A single-precision floating point number equivalent to the numeric value or symbol specified in s.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.
FormatException	s is not a number in a valid format.
OverflowException	s represents a number less than Single.MinValue or greater than Single.MaxValue.

The s parameter can contain NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[ws][sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits][ws]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

ws A series of white space characters. sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Runs of integral-digits can be partitioned by a group-separator symbol. (For example, in some cultures a comma (,) separates groups of thousands.) Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' An uppercase or lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of s are "100", "-123,456,789", "123.45+e6", "+500", "5e2", "3.1416", "600.", "-.123", and "-Infinity".

This version of Parse uses the NumberStyles values, NumberStyles.Float and NumberStyles.AllowThousands, and the specified number format information. If provider is null or a NumberFormatInfo cannot be obtained, the formatting information for the current system culture is used.

For more information about numeric formats, see the the conceptual topic at MSDN: formattingoverview topic.

Return to top

Summary

Converts the string representation of a number in a specified style to its single-precision floating point number equivalent.

C# Syntax:

public static float Parse(    string s,    NumberStyles style );

s

A string representing a number to convert.

style

The combination of one or more NumberStyles constants that indicate the permitted format of s.

Return Value:

A single-precision floating point number equivalent to the numeric value or symbol specified in s.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.
FormatException	s is not a number in a valid format.
OverflowException	s represents a number less than Single.MinValue or greater than Single.MaxValue.

The s parameter can contain NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[ws][sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits][ws]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

ws A series of white space characters. sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Runs of integral-digits can be partitioned by a group-separator symbol. (For example, in some cultures a comma (,) separates groups of thousands.) Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' An uppercase or lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of s are "100", "-123,456,789", "123.45+e6", "+500", "5e2", "3.1416", "600.", "-.123", and "-Infinity".

This version of Parse uses the specified NumberStyles and the culture-specific NumberFormatInfo data associated with the current thread.

For more information about numeric formats, see the the conceptual topic at MSDN: formattingoverview topic.

Return to top

Summary

Converts the string representation of a number in a specified style and culture-specific format to its single-precision floating point number equivalent.

C# Syntax:

public static float Parse(    string s,    NumberStyles style,    IFormatProvider provider );

s

A string representing a number to convert.

style

The combination of one or more NumberStyles constants that indicate the permitted format of s.

provider

An IFormatProvider that supplies culture-specific formatting information about s.

Return Value:

A single-precision floating point number equivalent to the numeric value or symbol specified in s.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.
FormatException	s is not a numeric value.
ArgumentException	style is not a combination of bit flags from the NumberStyles enumeration.

The s parameter can contain NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[ws][sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits][ws]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

ws A series of white space characters. sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Runs of integral-digits can be partitioned by a group-separator symbol. (For example, in some cultures a comma (,) separates groups of thousands.) Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' An uppercase or lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of s are "100", "-123,456,789", "123.45+e6", "+500", "5e2", "3.1416", "600.", "-.123", and "-Infinity".

This version of Parse uses the specified NumberStyles and the specified number format information. If provider is null or a NumberFormatInfo cannot be obtained, the formatting information for the current system culture is used.

For more information about numeric formats, see the the conceptual topic at MSDN: formattingoverview topic.

Return to top

Summary

Converts the numeric value of this instance to its equivalent string representation.

C# Syntax:

public override string ToString();

Return Value:

The string representation of the value of this instance.

The return value can be NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' A lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of the return value are "100", "-123,456,789", "123.45+e6", "500", "3.1416", "600", "-0.123", and "-Infinity".

This version of ToString uses the general format specifier ("G") and the NumberFormatInfo for the current culture.

Return to top

Summary

Converts the numeric value of this instance to its equivalent string representation using the specified culture-specific format information.

C# Syntax:

public string ToString(    IFormatProvider provider );

provider

An IFormatProvider that supplies culture-specific formatting information.

Return Value:

The string representation of the value of this instance as specified by provider.

The return value can be NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' A lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of the return value are "100", "-123,456,789", "123.45+e6", "500", "3.1416", "600", "-0.123", and "-Infinity".

This instance is formatted with the general format specifier ("G").

The provider parameter is an IFormatProvider that obtains a NumberFormatInfo that supplies culture-specific format information. If provider is null, the return value is formatted with NumberFormatInfo data for the current culture.

Return to top

Summary

Converts the numeric value of this instance to its equivalent string representation, using the specified format.

C# Syntax:

public string ToString(    string format );

format

A format string.

Return Value:

The string representation of the value of this instance as specified by format.

Exceptions

Exception Type	Condition
FormatException	format is invalid.

The return value can be NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' A lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of the return value are "100", "-123,456,789", "123.45+e6", "500", "3.1416", "600", "-0.123", and "-Infinity".

If format is null or an empty string, the return value is formatted with the general format specifier ("G").

By default, the return value only contains 7 digits of precision although a maximum of 9 digits is maintained internally. If the value of this instance has greater than 7 digits, ToString returns NumberFormatInfo.PositiveInfinitySymbol or NumberFormatInfo.NegativeInfinitySymbol instead of the expected number. If you require more precision, specify format with the "G9" format specification, which always returns 9 digits of precision, or "R", which returns 7 digits if the number can be represented with that precision or 9 digits if the number can only be represented with maximum precision.

The return value is formatted with NumberFormatInfo data for the current culture.

Return to top

Summary

Converts the numeric value of this instance to its equivalent string representation using the specified format and culture-specific format information.

C# Syntax:

public string ToString(    string format,    IFormatProvider provider );

format

A format specification.

provider

An IFormatProvider that supplies culture-specific formatting information.

Return Value:

The string representation of the value of this instance as specified by format and provider.

The return value can be NumberFormatInfo.PositiveInfinitySymbol, NumberFormatInfo.NegativeInfinitySymbol, NumberFormatInfo.NaNSymbol, or a string of the form:

[sign]integral-digits[.[fractional-digits]][e[sign]exponential-digits]

Optional items are framed in square brackets ([ and ]). Items containing the term "digits" consist of a series of numeric characters ranging from 0 to 9.

sign A negative sign or positive sign symbol. integral-digits A series of digits specifying the integral part of the number. Integral-digits can be absent if there are fractional-digits. '.' A culture-specific decimal point symbol. fractional-digits A series of digits specifying the fractional part of the number. 'e' A lowercase character 'e', indicating exponential (scientific) notation. exponential-digits A series of digits specifying an exponent.

Some examples of the return value are "100", "-123,456,789", "123.45+e6", "500", "3.1416", "600", "-0.123", and "-Infinity".

If format is null or an empty string, the return value for this instance is formatted with the general format specifier ("G").

By default, the return value only contains 7 digits of precision although a maximum of 9 digits is maintained internally. If the value of this instance has greater than 7 digits, ToString returns NumberFormatInfo.PositiveInfinitySymbol or NumberFormatInfo.NegativeInfinitySymbol instead of the expected number. If you require more precision, specify format with the "G9" format specification, which always returns 9 digits of precision, or "R", which returns 7 digits if the number can be represented with that precision or 9 digits if the number can only be represented with maximum precision.

The provider parameter is an IFormatProvider that obtains a NumberFormatInfo that supplies culture-specific format information. If provider is null, the return value is formatted with NumberFormatInfo data for the current culture.

Return to top

Top of page