DataType

Single

Description

A Single is an intrinsic data type that represents a Single-precision floating-point number. The default value of a Single is 0.0.

Methods

Name

Parameters

Returns

Shared

Equals

numValue As Double, maxUIps As Integer

Boolean

FromString

theString As String, Optional locale As Locale

Single

✓

FromText

theText As String, Optional locale As Locale

Single

✓

IsInfinite

Boolean

IsNotANumber

Boolean

Parse

theText As String, Optional locale As Locale

Single

✓

ToString

Optional locale As Locale, format As String = ""

String

Method descriptions

Single.Equals

Equals(numValue As Double, maxUIps As Integer) As Boolean

Tests whether two Single or Double numbers are equal within a specified tolerance.

Use Equals rather than = when you need to determine whether two floating point numbers are close enough in value to be considered “equal.” This can be used to account for the imprecision of floating point division on computers, for example. It allows for a user-specified rounding error.

For maxUIps, the last position refers to the the last byte in the binary representation of the mantissa. maxUIps is the amount of difference between the last byte of the 2 numbers that is still acceptable. For example, consider these 2 numbers:

3.1415926535897932 // last byte value is 0x18
3.141592653589795 // last byte value is 0x1C

A maxUIps of 3 will result in “not equal”, while a maxUIps of 4 will result in “equal”.

More information: https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/

Compare two values:

// 2 double values that vary by a tiny bit
Var d1 As Double = 3.1415926535897935
Var d2 As Double = 3.1415926535897933

If d1 = d2 Then
   // Will not get here because they are not an exact match
End If

If d1.Equals(d2, 1) Then
   // Will get here because they are "close enough"
End If

Single.FromString

FromString(theString As String, Optional locale As Locale) As Single

Converts a String value that containing a number that can be represented as a Single to a Single.

This method is shared.

If no locale is specified, then Locale.Raw is used.

Convert a String value to a Single:

Var userValue As String
userValue = "123.45"

Var d As Single
d = Single.FromString(userValue)

Single.FromText

FromText(theText As String, Optional locale As Locale) As Single

Converts a Text value that containing a number that can be represented as a Single to a Single.

This method is shared.

If no locale is specified, then Locale.Raw is used.

Convert a Text value to a Single:

Var userValue As Text
userValue = "123.45"

Var d As Single
d = Single.FromText(userValue)

Single.IsInfinite

IsInfinite As Boolean

Returns True if the value is infinite.

Single.IsNotANumber

IsNotANumber As Boolean

Returns True if the value is Not-A-Number.

Single.Parse

Parse(theText As String, Optional locale As Locale) As Single

Converts theText to a Single value.

This method is shared.

If no locale is specified, then Locale.Raw is used.

Numbers are converted only if they are found at the beginning of the text. Any numbers that follow a non-numeric value are ignored. Empty text returns 0.

Var d As Single
d = Single.Parse("123ABC")
// d = 123

Single.ToString

ToString(Extends value As Single, Optional locale As Locale, format As String = "") As String

Converts a Single value to a String value using the supplied locale and format.

If no locale is specified, then Locale.Raw is used.

Refer to Unicode Number Format Patterns for a list of formats.

Convert Singles values to String:

Var s As Single = 123.45
MessageBox(d.ToString)

Var n As Single = 1239.4567
Var t As String = n.ToString(Locale.Current, "#,###.##") // t = 1,239.46

Var n2 As Single = 12
Var t2 As String = n.ToString(Locale.Current, "#.00") // t2 = 12.00

Notes

Single is an IEEE Single-precision, floating-point value that uses 4 bytes. This means it is speedy but has some limitations in the type of values it can contain. For more information, refer to the wikipedia page about floating point.

In nearly all cases you should use a Double instead of a Single. The only practical cases where you ought to use a Single is when you need to specifically pass a Single-precision floating point number to an external function using a Declare.

You should use Currency when dealing with monetary values.

The VarType function returns a value of 4 when passed a Single.

Numerical limits

  • The maximum value of a Single is: ±3.40282346638528859811704183484516925e+38

  • The minimum value towards zero is: ±1.40129846432481707092372958328991613e-45

Nan and infinity

Singles can hold some special values described below: * NaN (i.e. “Not a Number”): occurs if you attempted to perform an illegal mathematical operation, like getting the square root of a negative number. Any further calculation made with a NaN will lead to a NaN value. Str or Format methods return a string beginning with “NaN”, e.g. “NaN(021)”. * Infinity: some calculations lead to an infinite result (positive or negative), e.g. Log( 0 ), or you may exceed the maximum value which can be hold. In such a case, a Single will be set to a special value, whose Str will return “INF” (for INFinity) or “-INF” (negative INFinity). Any further calculation will lead to a NaN or infinity value.

You can test for these using the IsInfinite and IsNotANumber methods.

Sample code

The Single and Double data types allow you to store and manage floating point numbers.

Var s As Single
s = 3.1416

Compatibility

All projects types on all supported operating systems.

See also