# Conversion module

The **Conversion** module groups together the procedures that produce a value of one type from a value of another --- coercing between the intrinsic numeric types, parsing numbers out of strings, formatting numbers as strings, and a handful of related utilities for handling **Null**, error values, and alternate numeric bases.

## Coercing to a specific type

The largest group is the family of **C**-prefixed functions, one per intrinsic data type. Each accepts any valid expression and produces a value of the named type, raising a run-time error if the conversion is not possible: [**CBool**](/tB/Modules/Conversion/CBool.md), [**CByte**](/tB/Modules/Conversion/CByte.md), [**CCur**](/tB/Modules/Conversion/CCur.md), [**CDate**](/tB/Modules/Conversion/CDate.md), [**CDbl**](/tB/Modules/Conversion/CDbl.md), [**CDec**](/tB/Modules/Conversion/CDec.md), [**CInt**](/tB/Modules/Conversion/CInt.md), [**CLng**](/tB/Modules/Conversion/CLng.md), [**CLngLng**](/tB/Modules/Conversion/CLngLng.md), [**CLngPtr**](/tB/Modules/Conversion/CLngPtr.md), [**CSng**](/tB/Modules/Conversion/CSng.md), [**CStr**](/tB/Modules/Conversion/CStr.md), and [**CVar**](/tB/Modules/Conversion/CVar.md).

Beyond their narrowing or widening behaviour, the C-prefix functions are *locale-aware* --- they honour the current decimal separator and short date format --- which makes them the right choice for parsing values that originated as user input. They also serve as documentation: writing `CLng(x)` makes the intended type of an intermediate result explicit even where the surrounding context would coerce *x* implicitly.

```tb check_build
Dim Amount As Currency
Amount = CCur("1,234.56")        ' parses with the local decimal separator
```

Two further constructors return a **Variant** whose subtype is fixed: [**CVDate**](/tB/Modules/Conversion/CVDate.md) builds a **Variant** of subtype **Date** (kept for compatibility with code written before **Date** became an intrinsic type), and [**CVErr**](/tB/Modules/Conversion/CVErr.md) builds a **Variant** of subtype **Error** containing a chosen error number --- the canonical way for a **Variant**-returning function to signal "this call failed with this error code" without raising a run-time error.

## Generic conversion

[**CType**](/tB/Modules/Conversion/CType.md) is a twinBASIC extension that takes its target type as a generic parameter, written `CType(Of `*type*`)(`*value*`)`. It plays the same role as the C-prefix functions but for any type known to the compiler, which makes it the standard cast for **Enum** values, interfaces, and user-defined types where no fixed-name function exists. **CType** doubles as a pointer-to-UDT cast --- see [Enhanced Pointer Functionality](/Features/Language/Pointers.md#ctypeof-type).

```tb check_build
Dim day As VbDayOfWeek
day = CType(Of VbDayOfWeek)(1)
```

## Truncating to an integer

[**Int**](/tB/Modules/Conversion/Int.md) and [**Fix**](/tB/Modules/Conversion/Fix.md) both discard the fractional part of a number, but they round in opposite directions for negative input. **Int** rounds toward negative infinity, so `Int(-8.4)` is `-9`; **Fix** truncates toward zero, so `Fix(-8.4)` is `-8`. For positive values the two coincide. Neither changes the data type of its argument, in contrast to [**CInt**](/tB/Modules/Conversion/CInt.md) and [**CLng**](/tB/Modules/Conversion/CLng.md), which both round and narrow to a specific integer type.

```tb check_build
Debug.Print Int(-8.4)            ' -9
Debug.Print Fix(-8.4)            ' -8
```

## Numbers, strings, and bases

[**Str**](/tB/Modules/Conversion/Str.md), [**Hex**](/tB/Modules/Conversion/Hex.md), [**Oct**](/tB/Modules/Conversion/Oct.md), and [**Bin**](/tB/Modules/Conversion/Bin.md) all return a printable string representation of a number --- **Str** in decimal, **Hex** in base 16, **Oct** in base 8, and **Bin** in base 2. Going the other way, [**Val**](/tB/Modules/Conversion/Val.md) and [**ValDec**](/tB/Modules/Conversion/ValDec.md) parse leading digits out of a string, returning a **Double** or **Decimal** respectively; both stop at the first unrecognised character and both honour the `&H` and `&O` radix prefixes for hexadecimal and octal literals.

These six functions are *culture-invariant* --- they always use the period (`.`) as the decimal separator and never read or write a thousands separator --- which makes them appropriate for round-tripping through a fixed file format or wire protocol. For locale-aware conversion to and from text, use [**CStr**](/tB/Modules/Conversion/CStr.md) and [**CDbl**](/tB/Modules/Conversion/CDbl.md) (or [**CDec**](/tB/Modules/Conversion/CDec.md)) instead.

```tb check_build
Debug.Print Hex(255)             ' "FF"
Debug.Print Oct(8)               ' "10"
Debug.Print Val("&HFF")          ' 255
```

## Working with Null and error values

[**Nz**](/tB/Modules/Conversion/Nz.md) returns a substitute value when its argument is **Null**, leaving any other value unchanged. It is most useful for reading nullable columns from a database recordset, where directly concatenating or arithmetically combining the field with another value would otherwise propagate **Null** through the rest of the expression.

[**Error**](/tB/Modules/Conversion/Error.md) returns the descriptive text associated with an error number --- the same text that would appear as the **Description** of an [**ErrObject**](/tB/Modules/ErrObject/index.md) raised with that number. It is the function counterpart to the same-named [**Error** statement](/tB/Core/Error.md), which *raises* a run-time error rather than describing one.

## Macintosh compatibility

[**MacID**](/tB/Modules/Conversion/MacID.md) packs a four-character Macintosh resource type or application signature into a **Long** for use with [**Dir**](/tB/Modules/FileSystem/Dir.md), [**Kill**](/tB/Modules/FileSystem/Kill.md), **Shell**, or [**AppActivate**](/tB/Modules/Interaction/AppActivate.md). twinBASIC currently targets Windows, where the value has no special meaning to those functions; **MacID** is provided for source compatibility with VBA code originally written for the classic Mac.

## Members

- [Bin](/tB/Modules/Conversion/Bin.md) -- returns the binary representation of a number as a string
- [CBool](/tB/Modules/Conversion/CBool.md) -- converts an expression to a **Boolean**
- [CByte](/tB/Modules/Conversion/CByte.md) -- converts an expression to a **Byte**
- [CCur](/tB/Modules/Conversion/CCur.md) -- converts an expression to a **Currency**
- [CDate](/tB/Modules/Conversion/CDate.md) -- converts a date/time expression to a **Date**
- [CDbl](/tB/Modules/Conversion/CDbl.md) -- converts an expression to a **Double**
- [CDec](/tB/Modules/Conversion/CDec.md) -- converts an expression to a **Decimal**
- [CInt](/tB/Modules/Conversion/CInt.md) -- converts an expression to an **Integer**
- [CLng](/tB/Modules/Conversion/CLng.md) -- converts an expression to a **Long**
- [CLngLng](/tB/Modules/Conversion/CLngLng.md) -- converts an expression to a **LongLong**
- [CLngPtr](/tB/Modules/Conversion/CLngPtr.md) -- converts an expression to a **LongPtr**
- [CSng](/tB/Modules/Conversion/CSng.md) -- converts an expression to a **Single**
- [CStr](/tB/Modules/Conversion/CStr.md) -- converts an expression to a **String**
- [CType](/tB/Modules/Conversion/CType.md) -- generic type conversion supporting the **CType(Of *type*)** cast operator
- [CVar](/tB/Modules/Conversion/CVar.md) -- converts an expression to a **Variant**
- [CVDate](/tB/Modules/Conversion/CVDate.md) -- converts a date/time expression to a **Variant** of subtype **Date**
- [CVErr](/tB/Modules/Conversion/CVErr.md) -- converts a numeric expression to a **Variant** of subtype **Error**
- [Error](/tB/Modules/Conversion/Error.md) -- returns the error message that corresponds to a given error number
- [Fix](/tB/Modules/Conversion/Fix.md) -- returns the integer portion of a number, truncating toward zero
- [Hex](/tB/Modules/Conversion/Hex.md) -- returns the hexadecimal representation of a number as a string
- [Int](/tB/Modules/Conversion/Int.md) -- returns the integer portion of a number, rounding toward negative infinity
- [MacID](/tB/Modules/Conversion/MacID.md) -- on the Macintosh, converts a 4-character constant to a value usable by **Dir**, **Kill**, **Shell**, or **AppActivate**
- [Nz](/tB/Modules/Conversion/Nz.md) -- replaces a **Null** value with a specified replacement value
- [Oct](/tB/Modules/Conversion/Oct.md) -- returns the octal representation of a number as a string
- [Str](/tB/Modules/Conversion/Str.md) -- returns the string representation of a number
- [Val](/tB/Modules/Conversion/Val.md) -- parses a string into a **Double**
- [ValDec](/tB/Modules/Conversion/ValDec.md) -- parses a string into a **Decimal**
