Method

# Str

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

## Description

Returns the `string</api/data_types/string>` form of the value passed. When dealing with numbers you can optionally format the number using US/English notation. Use the related `Val</api/text/val>` function to convert strings to numbers. Use the `Format</api/text/format>` function to format the number using the system locale settings for numerical display.

## Usage

``` xojo
result = Str(value [, format ])
```

| Part   | Type                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|--------|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| result | `String</api/data_types/string>` | The `string</api/data_types/string>` version of the value passed. For numbers, it returns the number as a `string</api/data_types/string>`. For `dates</api/data_types/datetime>`, it returns the date as a `string</api/data_types/string>` in SQL date/time format, *YYYY-MM-DD HH:MM:SS*. For `Colors</api/data_types/color>`, it returns the string value of the `Color</api/data_types/color>` as a `Hex</api/text/hex>` number in the format, `&h</api/language/literals/h>`AARRGGBB. Result has ASCII encoding. |
| value  | Variant                          | Any numeric, `Boolean</api/data_types/boolean>`, `DateTime</api/data_types/datetime>` or `Color</api/data_types/color>` expression.                                                                                                                                                                                                                                                                                                                                                                                    |
| format | String                           | Optional parameter to specify the format in a non-locale savvy way. For example:                                                                                                                                                                                                                                                                                                                                                                                                                                       |

## Notes

For real numbers, <span class="title-ref">Str</span> returns 7 decimal places. In most cases, this translates to 7 significant digits. For small numbers (between .01 and 0.00001) you do not get 7 significant digits because of truncation. For numbers below 0.00001, <span class="title-ref">Str</span> automatically switches to scientific notation and you then get 7 significant digits.

Str assumes that the period (.) is the decimal separator and the comma (,) is the thousands separator. If your application needs to recognize other separators, use the `CStr</api/text/cstr>` or `Format</api/text/format>` functions.

If you pass a `Boolean</api/data_types/boolean>`, <span class="title-ref">Str</span> will return either the string "True" or "False". If you pass a <span class="title-ref">Color</span>, it will return the hex representation of the color as a `String</api/data_types/string>` in the format `&hAARRGGBB`, where `AA` is the alpha channel. If you pass a `DateTime</api/data_types/datetime>`, it will return the value of the date in SQL Date-time format.

Use the `Format</api/text/format>` function when you want to convert numeric values into formatted strings such as dates, times, currency, etc.

## Sample code

This example uses the <span class="title-ref">Str</span> function to return the `string</api/data_types/string>` form of several values:

``` xojo
Var s As String
s = Str(123) ' returns "123"
s = Str(-123.44) ' returns "-123.44"
s = Str(123.0045) ' returns "123.0045"

Const kPi = 3.14159265
s = Str(kPi) ' returns "3.141593"
s = Str(314159265) ' returns "314159265"

' Boolean conversion
s = Str(True) ' returns True

' Thousands separator
Var i As Integer = 123456
Var result As String = Str(i, "###,###") ' 123,456 regardless of locale

' Colors convert to a hexadecimal number
Var c As Color = Color.DarkTingeColor
MessageBox(Str(c))

' Dates convert to SQLDateTime
Var d As DateTime = DateTime.Now
MessageBox(Str(d))
```

## Compatibility

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

<div class="seealso">

`Boolean</api/data_types/boolean>`, `Color</api/data_types/color>`, `DateTime</api/data_types/datetime>` datatypes; `String.ToDouble<string.todouble>`, `CStr</api/text/cstr>`, `Format</api/text/format>`, `Val</api/text/val>` functions.

</div>