From Xojo Documentation

Revision as of 13:14, 28 January 2021 by PLefebvre (talk | contribs)
You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Str(value As <Any Numeric>, format As String) As String

Supported for all project types and targets.

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



Part Type Description
result String The string version of the value passed. For numbers, it returns the number as a string. For dates, it returns the date as a string in SQL date/time format, YYYY-MM-DD HH:MM:SS. For Colors, it returns the string value of the Color as a Hex number in the format, &hRRGGBB. Result has ASCII encoding.
value Variant Any numeric, Boolean, Date or Color expression.
format String Optional parameter to specify the format in a non-locale savvy way. For example:

Str(95.65, "##.##") would use the "." as the decimal separator no matter what the user's locale setting is. Similarly, the comma is used as the thousands separator regardless of locale.


For real numbers, Str returns 7 decimal places. In most cases, this translates to 7 significant digits. For small numbers (between .01and 0.00001) you do not get 7 significant digits because of truncation. For numbers below 0.00001, Str 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 or Format functions.

If you pass a Boolean, Str will return either the string "True" or "False". If you pass a Color, it will return the hex representation of the color as a String. If you pass a Date, it will return the value of the date in SQL Date-time format.

Use the Format function when you want to convert numeric values into formatted strings such as dates, times, currency, etc.


This example uses the Str function to return the string form of several values:

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

// Dates convert to SQLDateTime
Var d As New Date

See Also

Boolean, Color, Date datatypes; CDbl, CStr, Format, Val functions.