DataType

# Single

<div class="rst-class">

forsearch

</div>

DataType

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

A <span class="title-ref">Single</span> is an intrinsic data type that represents a <span class="title-ref">Single</span>-precision floating-point number. The default value of a <span class="title-ref">Single</span> is 0.0.

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                | Parameters                                                                                                       | Returns                            | Shared |
|-------------------------------------|------------------------------------------------------------------------------------------------------------------|------------------------------------|--------|
| `Equals<single.equals>`             | numValue As `Double</api/data_types/double>`, maxUIps As `Integer</api/data_types/integer>`                      | `Boolean</api/data_types/boolean>` |        |
| `FromString<single.fromstring>`     | value As `String</api/data_types/string>`, locale As `Locale</api/os/locale>` = `Nil</api/language/nil>`         | Single                             | ✓      |
| `IsInfinite<single.isinfinite>`     |                                                                                                                  | `Boolean</api/data_types/boolean>` |        |
| `IsNotANumber<single.isnotanumber>` |                                                                                                                  | `Boolean</api/data_types/boolean>` |        |
| `Parse<single.parse>`               | value As `String</api/data_types/string>`, `Optional</api/language/optional>` locale As `Locale</api/os/locale>` | Single                             | ✓      |
| `ToString<single.tostring>`         | locale As `Locale</api/os/locale>` = `Nil</api/language/nil>`, format As `String</api/data_types/string>` = ""   | `String</api/data_types/string>`   |        |

## Method descriptions

<div id="single.equals">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Single.Equals

**Equals**(numValue As `Double</api/data_types/double>`, maxUIps As `Integer</api/data_types/integer>`) As `Boolean</api/data_types/boolean>`

> Tests whether two <span class="title-ref">Single</span> or `Double</api/data_types/double>` numbers are equal within a specified tolerance.
>
> Use Equals rather than `=</api/language/operators/comparison/equals_operator>` 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:
>
> ``` xojo
> 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:
>
> ``` xojo
> ' 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
> ```

<div id="single.fromstring">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Single.FromString

**FromString**(value As `String</api/data_types/string>`, locale As `Locale</api/os/locale>` = `Nil</api/language/nil>`) As Single

> Converts a String value that containing a number that can be represented as a <span class="title-ref">Single</span> to a <span class="title-ref">Single</span>.
>
> This method is `shared</api/language/shared>`.
>
> If no *locale* is specified, then `Locale.Raw<locale.raw>` is used.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> The *locale* parameter is not currently supported for Android.
>
> </div>
>
> Convert a String value to a \`Single\`:
>
> ``` xojo
> Var userValue As String
> userValue = "123.45"
>
> Var d As Single
> d = Single.FromString(userValue)
> ```

<div id="single.isinfinite">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Single.IsInfinite

**IsInfinite** As `Boolean</api/data_types/boolean>`

> Returns `True</api/language/true>` if the value is infinite.

<div id="single.isnotanumber">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Single.IsNotANumber

**IsNotANumber** As `Boolean</api/data_types/boolean>`

> Returns `True</api/language/true>` if the value is a Signaling NaN (sNaN). Quiet NaN (qNaN) values are not detected by this method.

<div id="single.parse">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Single.Parse

**Parse**(value As `String</api/data_types/string>`, locale As `Locale</api/os/locale>` = `Nil</api/language/nil>`) As Single

> Converts value to a <span class="title-ref">Single</span> value.
>
> This method is `shared</api/language/shared>`.
>
> If no *locale* is specified, then `Locale.Raw<locale.raw>` is used.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> The *locale* parameter is not currently supported for Android.
>
> </div>
>
> 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.
>
> ``` xojo
> Var d As Single
> d = Single.Parse("123ABC")
> ' d = 123
> ```

<div id="single.tostring">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Single.ToString

**ToString**(`Extends</api/language/extends>` value As Single, locale As `Locale</api/os/locale>` = `Nil</api/language/nil>`, format As `String</api/data_types/string>` = "") As `String</api/data_types/string>`

> Converts a <span class="title-ref">Single</span> value to a String value using the supplied locale and format.
>
> If no *locale* is specified, then `Locale.Raw<locale.raw>` is used.
>
> Refer to [Unicode Number Format Patterns](http://unicode.org/reports/tr35/tr35-4.html#Number_Format_Patterns) for a list of formats.
>
> Convert Singles values to String:
>
> ``` xojo
> Var s As Single = 123.45
> MessageBox(s.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
> ```
>
> The format string can contain up to three sections separated by semicolons to control the output for positive, negative, and zero values independently:
>
> ``` xojo
> Var amount As Single = 1239.45
> Var t As String = amount.ToString(Locale.Current, "#,##0.00;(#,##0.00);'-'")
> ' t = "1,239.45"
>
> amount = -1239.45
> t = amount.ToString(Locale.Current, "#,##0.00;(#,##0.00);'-'")
> ' t = "(1,239.45)"
>
> amount = 0.0
> t = amount.ToString(Locale.Current, "#,##0.00;(#,##0.00);'-'")
> ' t = "-"
> ```

## Notes

Single is an IEEE <span class="title-ref">Single</span>-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</api/data_types/double>` instead of a <span class="title-ref">Single</span>. The only practical cases where you ought to use a <span class="title-ref">Single</span> is when you need to specifically pass a <span class="title-ref">Single</span>-precision floating point number to an external function using a `Declare</api/language/declare>`.

You should use `Currency</api/data_types/currency>` when dealing with monetary values.

The `VarType</api/language/vartype>` function returns a value of 4 when passed a <span class="title-ref">Single</span>.

<span class="title-ref">Single</span> literals can be written using standard decimal notation, e.g. 3.14, or using scientific notation by following the number with "e" (or "E") and a signed exponent, e.g. 1.5e10 or 6.022e23.

``` xojo
Var s As Single = 1.5e10 ' s = 15000000000.0
Var s2 As Single = 6.022e23 ' s2 = 6.022e+23
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Numerical limits

- The maximum value of a <span class="title-ref">Single</span> 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</api/text/str>` or `Format</api/text/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 <span class="title-ref">Single</span> will be set to a special value, whose `Str</api/text/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<single.isinfinite>` and `IsNotANumber<single.isnotanumber>` methods.

## Sample code

The <span class="title-ref">Single</span> and `Double</api/data_types/double>` data types allow you to store and manage floating point numbers.

``` xojo
Var s As Single
s = 3.1416
```

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

- [Single precision floating point format on Wikipedia](http://en.wikipedia.org/wiki/Single_precision_floating-point_format) to learn more about the internal structure of a <span class="title-ref">Single</span>.
- `Double</api/data_types/double>`, `CGFloat</api/data_types/additional_types/cgfloat>`, `Currency</api/data_types/currency>` data types; `-</api/language/operators/mathematical/->`, `+</api/language/operators/mathematical/+>`, `*</api/language/operators/mathematical/x>`, `/</api/language/operators/mathematical/division>`, `<</api/language/operators/comparison/less_than>`, `\<=</api/language/operators/comparison/less_than_or_equal>`, `=</api/language/operators/comparison/equals_operator>`, `\>=</api/language/operators/comparison/greater_than_or_equal>`, `\></api/language/operators/comparison/greater_than>`, `<></api/language/operators/comparison/not_equal>`, `IsNumeric</api/language/isnumeric>`, `Mod</api/language/operators/mathematical/mod>`, `Val</api/text/val>`, `Str</api/text/str>`, `VarType</api/language/vartype>`, functions; `Var</api/language/var>` statement.
- `Equals</api/language/equals>` to compare Singles with a certain tolerance range.

</div>