From 9b2d82dadbb465de71985a8db3aa8df454579b72 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Fri, 30 Oct 2026 14:33:33 +0000 Subject: docs(types): explain implicit constructors and raw text literals Co-Authored-By: Claude Opus 5.5 --- AGENTS/PITFALLS/exceptions-and-c-interop.md | 6 +++--- AGENTS/PITFALLS/modules-and-stdlib.md | 3 ++- AGENTS/PITFALLS/overload-template-operator.md | 11 +++++++---- 3 files changed, 12 insertions(+), 8 deletions(-) (limited to 'AGENTS/PITFALLS') diff --git a/AGENTS/PITFALLS/exceptions-and-c-interop.md b/AGENTS/PITFALLS/exceptions-and-c-interop.md index b057d18..0d0f89d 100644 --- a/AGENTS/PITFALLS/exceptions-and-c-interop.md +++ b/AGENTS/PITFALLS/exceptions-and-c-interop.md @@ -19,11 +19,11 @@ Part of the [pitfalls index](../PITFALLS.md). ## C type extensions -- C_STRING is a raw char pointer, not a STRING: explicitly cast to STRING for - printing or string-library calls. +- C_STRING is a raw char pointer. A visible IMPLICIT STRING.NEW(C_STRING) + permits string-library calls, OUTPUT and file text; an explicit cast also works. - C aliases share canonical CIdentity; do not use LLVM widths to recover signedness or nominal type identity. Plain char's signedness is native, unlike pseudocode CHAR. -- C/pseudocode conversions require casts even for literals. C scalar arithmetic uses +- Other C/pseudocode conversions require casts, including numeric literals. C scalar arithmetic uses native promotions, but / always returns REAL. - Cast aliases must precede their use. - long double may have padding; sizeof does not identify its floating-point format. diff --git a/AGENTS/PITFALLS/modules-and-stdlib.md b/AGENTS/PITFALLS/modules-and-stdlib.md index 5394d78..e43bb78 100644 --- a/AGENTS/PITFALLS/modules-and-stdlib.md +++ b/AGENTS/PITFALLS/modules-and-stdlib.md @@ -17,7 +17,8 @@ Part of the [pitfalls index](../PITFALLS.md). and automatically linked. - Use -no-std before explicitly supplying a replacement STRING class/library; otherwise duplicate definitions fail. - - Ordinary literals require a visible STRING class with NEW(C_STRING). + - Double-quoted literals are raw C_STRING. STRING contexts, OUTPUT and file text + require a visible STRING class with IMPLICIT NEW(C_STRING), including under -no-std. - C_TYPE/INCLUDE/EXTERN syntax strings are parser metadata and do not construct STRING. - Keyword NEW/DELETE and MALLOC/REALLOC/FREE require memory.cps; -no-std users diff --git a/AGENTS/PITFALLS/overload-template-operator.md b/AGENTS/PITFALLS/overload-template-operator.md index 909e5f7..56247ff 100644 --- a/AGENTS/PITFALLS/overload-template-operator.md +++ b/AGENTS/PITFALLS/overload-template-operator.md @@ -9,8 +9,9 @@ Part of the [pitfalls index](../PITFALLS.md). - Count, canonical parameter types, array rank and (for non-VOID definitions) return type distinguish signatures; a PROCEDURE counts as VOID. BYREF/BYVAL and array bounds do not. -- Calls match exact static types, even for a single OVERLOAD definition; ordinary - functions still coerce arguments. A known expected result type (assignment, BYVAL +- Calls prefer exact static types, then marked IMPLICIT construction and the + existing CHAR/STRING bridge for scalar BYVAL parameters; ordinary functions + retain their existing numeric coercions. A known expected result type (assignment, BYVAL argument, RETURN, condition, subscript, CASE comparison) must match the overload's return type exactly; `(T) x` only prefers T and otherwise converts. Without a context, return-only-distinct candidates need one DEFAULT return or remain ambiguous. @@ -28,7 +29,8 @@ Part of the [pitfalls index](../PITFALLS.md). - Top-level FUNCTION/PROCEDURE/CLASS only; all template parameters are types, with at most one final pack. -- Exact types are required even with explicit arguments (`Max(1, 2.5)` fails). +- Substituted BYVAL parameters allow marked constructors and CHAR/STRING bridges, + but numeric widening still fails (`Max(1, 2.5)` fails). Deduction recognizes T and array element T, never the T inside Box. - When multiple ordinary/template functions share a name, every definition must specify OVERLOAD; exact ordinary definitions win, then non-variadic templates, then @@ -55,7 +57,8 @@ Part of the [pitfalls index](../PITFALLS.md). - Unary/binary operators require OVERLOAD FUNCTION, with supported arity and at least one record/class/enum operand. Pointer aliases alone do not qualify. -- Exact matching considers visible globals and left-class members together, and the +- Exact-first matching considers visible globals and left-class members together, + with marked BYVAL construction after directly supported builtins. The result type joins the match when the context supplies one; ties are errors, including private/public ties. Without a context, return-only-distinct candidates need a unique DEFAULT return or remain ambiguous; defaults do not resolve -- cgit v1.3.1-4-g156e