CByte, CBool, CCur, CDate, CDbl, CShort, CInt, CLong, CHandle, CLarge, CSng, CFloat, CStr, CVar Functions

Purpose

Each function coerces an expression to a specific data type.

Syntax

Bool = CBool(expression)

Byte = CByte(expression)

Currency = CCur(expression)

Date = CDate(expression)

Double = CDbl(expression)

Short = CShort(expression)

Integer = CInt(expression)

Long = CLong(expression)

Handle = CHandle(expression)

Large = CLarge(expression)

Single = CSng(expression)

Single = CFloat(expression)

String = CStr(expression)

Variant = CVar(expression)

Description

If the expression passed to the function is outside the range of the data type being converted to, an error occurs.

In general, you can document your code using the data-type conversion functions to show that the result of some operation should be expressed as a particular data type rather than the default data type. For example, use CCur to force currency arithmetic in cases where single-precision, double-precision, or integer arithmetic normally would occur.

You should use the data-type conversion functions instead of Val to provide internationally aware conversions from one data type to another. For example, when you use CCur, different decimal separators, different thousand separators, and various currency options are properly recognized depending on the locale setting of your computer.

Use the IsDate function to determine if date can be converted to a date or time. CDate recognizes date literals and time literals as well as some numbers that fall within the range of acceptable dates. When converting a number to a date, the whole number portion is converted to a date. Any fractional part of the number is converted to a time of day, starting at midnight.

CDate recognizes date formats according to the locale setting of your system; it also recognises dates without year values (e.g. 12/12), allocating the current year before returning a value. NOTE: the correct order of day, month, and year may not be properly determined if it is provided in a format other than one of the recognized date settings. In addition, a long date format is not recognized if it also contains the day-of-the-week string.

The base year, at least for Windows 98, was 1930; for Windows 10 it is 1950. This means that years specified with only two digits are interpreted based on 1930 and 1950 respectively. So in Windows 98, a year of "29" means 2029, and "31" means 1931 but in Windows 10, "29" means 2029 and "31" means 2031. Since this is OLE dependent, located in oleaut32.dll, differs between operating systems and cannot be adjusted, it is best to avoid two figure years if at all possible.

! The integer type conversion functions always round to the nearest even number! When the fractional part is exactly 0.5, CByte, CShort, CInt, CLong, and CLarge always round it to the nearest even number. For example, 0.5 rounds to 0, and 1.5 rounds to 2.

Print CInt(1.5)   // 2

Print CByte(0.5)  // 0

CByte, CShort, CInt, CLong, and CLarge differ from the Fix and Int functions, which truncate, rather than round, the fractional part of a number. Also, Fix and Int always return a value of the same type as is passed in.

Note CByte is the only function that returns an unsigned value (0 .. 256). A negative parameter is converted to a positive value.

CStr returns a string depending on the type of the argument passed:

Example

Print CBool(25 < 24 < 30) //result: True

Print CBool(25 > 24 > 30) //result: False

Print CByte(0.49999)      //result: 0

Print CByte(0.50001)      //result: 1

Print CByte(-1.6)         //result: 254

Dim v                     '= Null

Print CStr(12.2)          //result: 12.2

Print CStr(1 > 0)         //result: -1

Print CStr(v)             //result:

Print CStr(Date)          //result: today's date

Remarks

GFABasic does not support the Visual Basic functions CDec and CVErr (see this page for a workaround for the latter).

Integer conversions use the Gauss rule that if you are in an perfect half case, you must round to the nearest digit that can be divided by 2 (0,2,4,6,and 8). This rule is important to obtain more accurate results with rounded numbers after operation.

An example:

The "Gaussian" sum is nearer to the unrounded sum (difference of 0.0042 with Gaussian and 0.0058 with Standard rounding.)

Another example with half-round cases only:

Again, the "Gaussian" rounding result is nearer from the unrounded result than the "Standard" one.

See Also

Fix(), Int(), Round(), CByteRZ(), CIntRZ(), CLargeRZ(), CLongRZ(), CShortRZ()

{Created by Sjouke Hamstra; Last updated: 23/09/2021 by James Gaite}