From 64622b737f070b377fdef3fb31a67c084457bd7b Mon Sep 17 00:00:00 2001
From: _ov4 <ov4@ov4.org>
Date: Thu, 22 Oct 2026 15:11:38 +0000
Subject: feat(codegen)!: require explicit REAL to INTEGER conversion and add
 INT

Implicit REAL to INTEGER is now a compile error with an INT(...) hint.
INT is a compiler builtin that truncates toward zero and raises a runtime
error for NaN or values outside the INTEGER range.

No existing test program relied on the implicit conversion.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 doc/language/cpsc-language-overview.7.md     |  3 ++-
 doc/language/function/cpsc-function-int.7.md | 32 ++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 doc/language/function/cpsc-function-int.7.md

(limited to 'doc')

diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md
index 05001bd..b1376d8 100644
--- a/doc/language/cpsc-language-overview.7.md
+++ b/doc/language/cpsc-language-overview.7.md
@@ -10,7 +10,7 @@ Keywords are uppercase and case-sensitive. Identifiers, including built-in funct
 
 Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`, `<=`, and `>=`. Standard-library STRING comparisons compare contents, case-sensitively. Use `+`, `-`, `*`, and `/` for arithmetic; built-in `/` always returns REAL. Use `&` to join strings.
 
-User-defined types can overload operators with OVERLOAD FUNCTION OPERATOR; expressions then use the declared result type. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md). STRING cannot be implicitly converted to BOOLEAN. Typing is strict: arithmetic and unary minus accept only INTEGER and REAL, a comparison needs operands of the same type (or INTEGER with REAL), and BOOLEAN, CHAR and INTEGER never convert into one another implicitly (only INTEGER converts to REAL). Use ASC and CHR to move between CHAR and INTEGER.
+User-defined types can overload operators with OVERLOAD FUNCTION OPERATOR; expressions then use the declared result type. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md). STRING cannot be implicitly converted to BOOLEAN. Typing is strict: arithmetic and unary minus accept only INTEGER and REAL, a comparison needs operands of the same type (or INTEGER with REAL), and BOOLEAN, CHAR and INTEGER never convert into one another implicitly (only INTEGER converts to REAL). Use ASC and CHR to move between CHAR and INTEGER. REAL never converts to INTEGER implicitly; use INT.
 
 Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence.
 
@@ -83,6 +83,7 @@ These ordinary functions and the STRING class come from the embedded standard li
 # BUILT-IN FUNCTIONS
 
 - [cpsc-function-eof(7)](function/cpsc-function-eof.7.md): test for the end of a text file.
+- [cpsc-function-int(7)](function/cpsc-function-int.7.md): take the integer part of a number.
 - [cpsc-function-malloc(7)](function/cpsc-function-malloc.7.md): allocate raw memory.
 - [cpsc-function-realloc(7)](function/cpsc-function-realloc.7.md): resize an explicit allocation.
 - [cpsc-function-free(7)](function/cpsc-function-free.7.md): release an explicit allocation.
diff --git a/doc/language/function/cpsc-function-int.7.md b/doc/language/function/cpsc-function-int.7.md
new file mode 100644
index 0000000..245ae70
--- /dev/null
+++ b/doc/language/function/cpsc-function-int.7.md
@@ -0,0 +1,32 @@
+% CPSC-FUNCTION-INT(7)
+
+# NAME
+
+cpsc-function-int - take the integer part of a number
+
+# SYNOPSIS
+
+```text
+INT(value : REAL) RETURNS INTEGER
+INT(value : INTEGER) RETURNS INTEGER
+```
+
+# DESCRIPTION
+
+Built into the compiler, so it also works with `-no-std`.
+
+Return the integer part of a REAL, truncating toward zero: `INT(27.5415)` is 27 and `INT(-27.9)` is -27. An INTEGER argument is returned unchanged. A NaN or a value outside the INTEGER range stops the program with a runtime error.
+
+REAL never converts to INTEGER implicitly, so assignments, FOR bounds, array bounds and indices, arguments and RETURN values of type REAL are compile errors; wrap them in INT.
+
+# EXAMPLE
+
+```text
+DECLARE Whole : INTEGER
+Whole <- INT(27.5415)
+OUTPUT Whole
+```
+
+# SEE ALSO
+
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-div(7)](../keyword/cpsc-keyword-div.7.md).
-- 
cgit v1.3.1-4-g156e