Document the Conversion module.

docs/Reference/Categories.md

@@ -42,14 +42,26 @@ Statements:
 * [Select Case](../tB/Core/Select-Case) - execute a code block selected by an expression
 * [With](../tB/Core/With) - bring a variable or expression into scope
 * [Goto](../tB/Core/GoTo), [GoSub ... Return](../tB/Core/GoSub-Return) - transfer execution to another location
-* [Resume](../tB/Core/Resume) - resumes execution after an error has been caught
-* [On Error](../tB/Core/On-Error) - specifies what to do when an error occurs
 * [On ... GoTo](../tB/Core/On-GoTo), [On ... GoSub](../tB/Core/On-GoSub) - transfer execution to a location selected by an expression
 * [Stop](../tB/Core/Stop) - interrupt execution
 
 See also: 
 
 * [End](../tB/Core/End) - terminate execution.
+* [On Error](../tB/Core/On-Error), [Resume](../tB/Core/Resume) - flow control for run-time errors (see [Error Handling](#error-handling))
+
+## Error Handling
+
+Statements:
+
+* [On Error](../tB/Core/On-Error) - specifies what to do when an error occurs
+* [Resume](../tB/Core/Resume) - resumes execution after an error has been caught
+* [Error](../tB/Core/Error) statement - simulates the occurrence of an error (legacy; prefer **Err.Raise**)
+
+Procedures:
+
+* [Error$, Error](../tB/Modules/Conversion/Error) function - returns the error message that corresponds to a given error number
+* [CVErr](../tB/Modules/Conversion/CVErr) - wraps a numeric expression in a **Variant** of subtype **Error**
 
 ## Variable Declaration
 
@@ -99,6 +111,7 @@ Procedures:
 * [FileCopy](../tB/Core/FileCopy) - copy a file on disk
 * [Kill](../tB/Core/Kill) - delete a file from disk
 * [SavePicture](../tB/Core/SavePicture) - write a `Picture` or `Image` to a disk file
+* [MacID](../tB/Modules/Conversion/MacID) - convert a 4-character Mac file-type code (legacy)
 
 ## State Management
 
@@ -138,6 +151,44 @@ Procedures:
 * [Rnd](../tB/Modules/Math/Rnd) - generate a random number in the range [0.0, 1.0)
 * [Randomize](../tB/Modules/Math/Randomize) - seed the random number generator
 
+See also:
+
+* [Fix](../tB/Modules/Conversion/Fix), [Int](../tB/Modules/Conversion/Int) - extract the integer portion of a number
+* [CInt](../tB/Modules/Conversion/CInt), [CLng](../tB/Modules/Conversion/CLng), [CLngLng](../tB/Modules/Conversion/CLngLng), [CLngPtr](../tB/Modules/Conversion/CLngPtr) - coerce to integer types (rounds half-to-even)
+
+## Type Conversion
+
+Procedures that coerce an expression to a specific type:
+
+* [CBool](../tB/Modules/Conversion/CBool), [CByte](../tB/Modules/Conversion/CByte), [CCur](../tB/Modules/Conversion/CCur), [CDbl](../tB/Modules/Conversion/CDbl), [CDec](../tB/Modules/Conversion/CDec), [CInt](../tB/Modules/Conversion/CInt), [CLng](../tB/Modules/Conversion/CLng), [CLngLng](../tB/Modules/Conversion/CLngLng), [CLngPtr](../tB/Modules/Conversion/CLngPtr), [CSng](../tB/Modules/Conversion/CSng) - coerce to a specific numeric type
+* [CStr](../tB/Modules/Conversion/CStr) - coerce to **String** (locale-aware; preferred over [Str](../tB/Modules/Conversion/Str))
+* [CVar](../tB/Modules/Conversion/CVar) - coerce to **Variant**
+* [CDate](../tB/Modules/Conversion/CDate) - coerce to **Date**; [CVDate](../tB/Modules/Conversion/CVDate) returns a **Variant** of subtype **Date** (legacy)
+* [CType](../tB/Modules/Conversion/CType) - explicit cast operator with a caller-supplied target type (twinBASIC extension)
+
+Procedures that convert between numbers and strings:
+
+* [Hex$, Hex](../tB/Modules/Conversion/Hex) - hexadecimal string representation of a number
+* [Oct$, Oct](../tB/Modules/Conversion/Oct) - octal string representation of a number
+* [Str$, Str](../tB/Modules/Conversion/Str) - decimal string representation of a number
+* [Val](../tB/Modules/Conversion/Val) - parse a string into a **Double**
+* [ValDec](../tB/Modules/Conversion/ValDec) - parse a string into a **Decimal**
+
+Procedures that extract the integer portion of a number:
+
+* [Fix](../tB/Modules/Conversion/Fix) - truncates toward zero
+* [Int](../tB/Modules/Conversion/Int) - rounds toward negative infinity
+
+Other:
+
+* [Nz](../tB/Modules/Conversion/Nz) - replace **Null** with a default value
+
+See also:
+
+* [Format$, Format](../tB/Modules/Strings/Format) - locale-aware number formatting
+* [FormatNumber](../tB/Modules/Strings/FormatNumber), [FormatPercent](../tB/Modules/Strings/FormatPercent), [FormatCurrency](../tB/Modules/Strings/FormatCurrency), [FormatDateTime](../tB/Modules/Strings/FormatDateTime) - typed formatters
+* [CVErr](../tB/Modules/Conversion/CVErr), [Error$, Error](../tB/Modules/Conversion/Error) function - error helpers (see [Error Handling](#error-handling))
+
 ## String Handling
 
 Statements that modify strings:
@@ -176,6 +227,15 @@ Procedures that return modified strings:
 * [FormatNumber](../tB/Modules/Strings/FormatNumber) - formats an expression as a numeric string
 * [FormatPercent](../tB/Modules/Strings/FormatPercent) - formats an expression as a percent string
 
+Procedures that convert between numbers and strings:
+
+* [CStr](../tB/Modules/Conversion/CStr) - coerce a value to **String** (locale-aware)
+* [Hex$, Hex](../tB/Modules/Conversion/Hex) - hexadecimal string representation of a number
+* [Oct$, Oct](../tB/Modules/Conversion/Oct) - octal string representation of a number
+* [Str$, Str](../tB/Modules/Conversion/Str) - decimal string representation of a number
+* [Val](../tB/Modules/Conversion/Val) - parse a string into a **Double**
+* [ValDec](../tB/Modules/Conversion/ValDec) - parse a string into a **Decimal**
+
 See also:
 
 * [FormatCurrency](../tB/Modules/Strings/FormatCurrency) - format an expression as a currency string
@@ -190,6 +250,10 @@ Procedures:
 * [MonthName](../tB/Modules/Strings/MonthName) - returns the name of the specified month
 * [WeekdayName](../tB/Modules/Strings/WeekdayName) - returns the name of the specified day of the week
 
+See also:
+
+* [CDate](../tB/Modules/Conversion/CDate), [CVDate](../tB/Modules/Conversion/CVDate) - coerce an expression to **Date** or **Variant** (subtype **Date**)
+
 ## Introspection
 
 Procedures:
@@ -226,5 +290,4 @@ Procedures:
 Statements:
 
 * [DefBool, DefByte, DefInt, DefLng, DefCur, DefSng, DefDbl, DefDec, DefDate, DefStr, DefObj, DefVar](../tB/Core/Deftype) - used to give implicit types to single-letter variables
-* [Error](../tB/Core/Error) - raise an error
 

docs/Reference/Modules/Conversion/CBool.md

@@ -0,0 +1,41 @@
+---
+title: CBool
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CBool
+redirect_from:
+-  /tB/Core/CBool
+---
+# CBool
+{: .no_toc }
+
+Coerces an expression to a **Boolean**.
+
+Syntax: **CBool(** *expression* **)**
+
+*expression*
+: *required* Any valid string or numeric expression.
+
+The return type is **Boolean**. If *expression* evaluates to a nonzero value, **CBool** returns **True**; otherwise, it returns **False**.
+
+If *expression* cannot be interpreted as a numeric value, a run-time 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.
+
+### Example
+
+This example uses the **CBool** function to convert an expression to a **Boolean**.
+
+```tb
+Dim A, B, Check
+A = 5: B = 5             ' Initialize variables.
+Check = CBool(A = B)     ' Check contains True.
+
+A = 0                    ' Define variable.
+Check = CBool(A)         ' Check contains False.
+```
+
+### See Also
+
+- [CByte](CByte), [CInt](CInt), [CLng](CLng), [CDbl](CDbl), [CSng](CSng), [CStr](CStr), [CVar](CVar) functions
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Conversion/CByte.md

@@ -0,0 +1,34 @@
+---
+title: CByte
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CByte
+redirect_from:
+-  /tB/Core/CByte
+---
+# CByte
+{: .no_toc }
+
+Coerces an expression to a **Byte**.
+
+Syntax: **CByte(** *expression* **)**
+
+*expression*
+: *required* Any valid string or numeric expression in the range `0` to `255`.
+
+The return type is **Byte**. If *expression* is outside the range of a **Byte**, a run-time error occurs. Fractions are rounded — when the fractional part is exactly `0.5`, **CByte** rounds to the nearest even number.
+
+### Example
+
+This example uses the **CByte** function to convert an expression to a **Byte**.
+
+```tb
+Dim MyDouble, MyByte
+MyDouble = 125.5678          ' MyDouble is a Double.
+MyByte = CByte(MyDouble)     ' MyByte contains 126.
+```
+
+### See Also
+
+- [CBool](CBool), [CInt](CInt), [CLng](CLng), [CDbl](CDbl), [CSng](CSng), [CStr](CStr), [CVar](CVar) functions
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Conversion/CCur.md

@@ -0,0 +1,40 @@
+---
+title: CCur
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CCur
+redirect_from:
+-  /tB/Core/CCur
+---
+# CCur
+{: .no_toc }
+
+Coerces an expression to a **Currency**.
+
+Syntax: **CCur(** *expression* **)**
+
+*expression*
+: *required* Any valid string or numeric expression in the range `-922,337,203,685,477.5808` to `922,337,203,685,477.5807`.
+
+The return type is **Currency**. If *expression* is outside that range, a run-time error occurs.
+
+Use **CCur** to force currency arithmetic in cases where single-precision, double-precision, or integer arithmetic normally would occur.
+
+You should use **CCur** instead of **Val** to provide internationally aware conversions from one data type to another. **CCur** recognizes different decimal separators, different thousand separators, and various currency options properly, depending on the locale setting of your computer.
+
+### Example
+
+This example uses the **CCur** function to convert an expression to a **Currency**.
+
+```tb
+Dim MyDouble, MyCurr
+MyDouble = 543.214588                    ' MyDouble is a Double.
+MyCurr = CCur(MyDouble * 2)              ' Convert result of MyDouble * 2
+                                         ' (1086.429176) to a
+                                         ' Currency (1086.4292).
+```
+
+### See Also
+
+- [CBool](CBool), [CByte](CByte), [CDbl](CDbl), [CDec](CDec), [CSng](CSng), [CStr](CStr), [CVar](CVar) functions
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Conversion/CDate.md

@@ -0,0 +1,43 @@
+---
+title: CDate
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CDate
+redirect_from:
+-  /tB/Core/CDate
+---
+# CDate
+{: .no_toc }
+
+Coerces an expression to a **Date**.
+
+Syntax: **CDate(** *expression* **)**
+
+*expression*
+: *required* Any valid date expression — a date literal, a date/time string, or a number that falls within the range of acceptable dates.
+
+The return type is **Date**.
+
+Use the **IsDate** function to determine whether *expression* 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. The correct order of day, month, and year may not be 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.
+
+[**CVDate**](CVDate) is also provided for compatibility with previous versions of Visual Basic. The syntax of **CVDate** is identical to **CDate**; however, **CVDate** returns a **Variant** whose subtype is **Date** instead of an actual **Date** type.
+
+### Example
+
+This example uses the **CDate** function to convert a string to a **Date**. In general, hard-coding dates and times as strings (as shown in this example) is not recommended. Use date literals and time literals, such as `#2/12/1969#` and `#4:45:23 PM#`, instead.
+
+```tb
+Dim MyDate, MyShortDate, MyTime, MyShortTime
+MyDate = "February 12, 1969"             ' Define date.
+MyShortDate = CDate(MyDate)              ' Convert to Date data type.
+
+MyTime = "4:35:47 PM"                    ' Define time.
+MyShortTime = CDate(MyTime)              ' Convert to Date data type.
+```
+
+### See Also
+
+- [CVDate](CVDate), [DateValue](../DateTime/DateValue), [TimeValue](../DateTime/TimeValue) functions
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Conversion/CDbl.md

@@ -0,0 +1,36 @@
+---
+title: CDbl
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CDbl
+redirect_from:
+-  /tB/Core/CDbl
+---
+# CDbl
+{: .no_toc }
+
+Coerces an expression to a **Double**.
+
+Syntax: **CDbl(** *expression* **)**
+
+*expression*
+: *required* Any valid string or numeric expression in the **Double** range — `-1.79769313486231E308` to `-4.94065645841247E-324` for negative values, and `4.94065645841247E-324` to `1.79769313486232E308` for positive values.
+
+The return type is **Double**. If *expression* is outside the range of a **Double**, a run-time error occurs.
+
+Use **CDbl** instead of [**Val**](Val) to provide internationally aware conversions from a string to a numeric type. **CDbl** recognizes different decimal separators and different thousand separators properly, depending on the locale setting of your computer.
+
+### Example
+
+This example uses the **CDbl** function to convert an expression to a **Double**.
+
+```tb
+Dim MyCurr, MyDouble
+MyCurr = CCur(234.456784)                    ' MyCurr is a Currency.
+MyDouble = CDbl(MyCurr * 8.2 * 0.01)         ' Convert result to a Double.
+```
+
+### See Also
+
+- [CCur](CCur), [CDec](CDec), [CInt](CInt), [CLng](CLng), [CSng](CSng), [CStr](CStr), [CVar](CVar) functions
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Conversion/CDec.md

@@ -0,0 +1,39 @@
+---
+title: CDec
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CDec
+redirect_from:
+-  /tB/Core/CDec
+---
+# CDec
+{: .no_toc }
+
+Coerces an expression to a **Decimal**.
+
+Syntax: **CDec(** *expression* **)**
+
+*expression*
+: *required* Any valid string or numeric expression. The range for zero-scaled numbers (no decimal places) is `±79,228,162,514,264,337,593,543,950,335`. For numbers with 28 decimal places, the range is `±7.9228162514264337593543950335`. The smallest possible non-zero number is `0.0000000000000000000000000001`.
+
+The return type is **Decimal**.
+
+> [!NOTE]
+> In VBA, **CDec** does not return a discrete data type; it always returns a **Variant** whose value has been converted to a **Decimal** subtype. In twinBASIC, **Decimal** is a full first-class data type, so **CDec** returns a **Decimal** directly. You can still assign the result to a **Variant** to obtain VBA-compatible behavior.
+
+Use **CDec** instead of [**Val**](Val) to provide internationally aware conversions from a string to a numeric type.
+
+### Example
+
+This example uses the **CDec** function to convert a numeric value to a **Decimal**.
+
+```tb
+Dim MyDecimal As Decimal, MyCurr As Currency
+MyCurr = 10000000.0587               ' MyCurr is a Currency.
+MyDecimal = CDec(MyCurr)             ' MyDecimal is a Decimal.
+```
+
+### See Also
+
+- [CCur](CCur), [CDbl](CDbl), [CSng](CSng), [ValDec](ValDec) functions
+
+{% include VBA-Attribution.md %}

docs/Reference/Modules/Conversion/CInt.md

@@ -0,0 +1,39 @@
+---
+title: CInt
+parent: Conversion Module
+permalink: /tB/Modules/Conversion/CInt
+redirect_from:
+-  /tB/Core/CInt
+---
+# CInt
+{: .no_toc }
+
+Coerces an expression to an **Integer**.
+
+Syntax: **CInt(** *expression* **)**
+
+*expression*
+: *required* Any valid string or numeric expression in the range `-32,768` to `32,767`. Fractions are rounded.
+
+The return type is **Integer**. If *expression* is outside the range of an **Integer**, a run-time error occurs.
+
+When the fractional part is exactly `0.5`, **CInt** always rounds it to the nearest even number. For example, `0.5` rounds to `0`, and `1.5` rounds to `2`. **CInt** differs from the [**Fix**](Fix) and [**Int**](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.
+
+Use **CInt** instead of [**Val**](Val) to provide internationally aware conversions from a string to a numeric type.
+
+### Example
+
+This example uses the **CInt** function to convert a value to an **Integer**.
+
+```tb
+Dim MyDouble, MyInt
+MyDouble = 2345.5678                 ' MyDouble is a Double.
+MyInt = CInt(MyDouble)               ' MyInt contains 2346.
+```
+
+### See Also
+
+- [CBool](CBool), [CByte](CByte), [CLng](CLng), [CLngLng](CLngLng), [CSng](CSng), [CStr](CStr), [CVar](CVar) functions
+- [Fix](Fix), [Int](Int) functions
+
+{% include VBA-Attribution.md %}