From 63109537383fa58c6a1db95f275d6b5de63b0015 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 28 Oct 2026 13:41:26 +0000 Subject: docs(overload): document default return selection Co-Authored-By: Claude Opus 5.5 --- doc/language/cpsc-language-overview.7.md | 3 +- .../function/cpsc-function-num_to_str.7.md | 7 ++-- .../function/cpsc-function-str_to_num.7.md | 14 +++++--- doc/language/keyword/cpsc-keyword-default.7.md | 42 ++++++++++++++++++++++ doc/language/keyword/cpsc-keyword-function.7.md | 2 +- doc/language/keyword/cpsc-keyword-operator.7.md | 2 +- doc/language/keyword/cpsc-keyword-overload.7.md | 6 ++-- doc/language/keyword/cpsc-keyword-procedure.7.md | 2 +- doc/language/keyword/cpsc-keyword-template.7.md | 2 +- 9 files changed, 65 insertions(+), 15 deletions(-) create mode 100644 doc/language/keyword/cpsc-keyword-default.7.md (limited to 'doc') diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md index 559a58d..da4d821 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. Ordinary identifiers, including built 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. OVERLOAD definitions may also differ by return type: a context that requires a result type selects the matching return type, while a cast only prefers it. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md) and [cpsc-keyword-overload(7)](keyword/cpsc-keyword-overload.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. CHAR and STRING do convert implicitly: a CHAR becomes a one-character STRING in `&`, in comparisons, in assignment, in argument passing and in RETURN, and a STRING becomes a CHAR in assignment, argument passing and RETURN (for example `c <- MID(s, i, 1)`); a STRING whose length is not 1 is a runtime error that TRY/CATCH can catch. REAL never converts to INTEGER implicitly; use INT. +User-defined types can overload operators with OVERLOAD FUNCTION OPERATOR; expressions then use the declared result type. OVERLOAD definitions may also differ by return type: a context that requires a result type selects the matching return type, while a cast only prefers it. `RETURNS DEFAULT type` selects a default when context cannot choose among return-only overloads. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md) and [cpsc-keyword-overload(7)](keyword/cpsc-keyword-overload.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. CHAR and STRING do convert implicitly: a CHAR becomes a one-character STRING in `&`, in comparisons, in assignment, in argument passing and in RETURN, and a STRING becomes a CHAR in assignment, argument passing and RETURN (for example `c <- MID(s, i, 1)`); a STRING whose length is not 1 is a runtime error that TRY/CATCH can catch. REAL never converts to INTEGER implicitly; use INT. Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence. @@ -47,6 +47,7 @@ PP_DEFINE and PP_UNDEF control file-local, case-sensitive preprocessor switches. - [cpsc-keyword-procedure(7)](keyword/cpsc-keyword-procedure.7.md): define a procedure and parameter modes. - [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md): overload unary and binary operators. - [cpsc-keyword-overload(7)](keyword/cpsc-keyword-overload.7.md): explicitly overload functions, procedures and constructors. +- [cpsc-keyword-default(7)](keyword/cpsc-keyword-default.7.md): choose a default return type for an overload. - [cpsc-keyword-template(7)](keyword/cpsc-keyword-template.7.md): define function, procedure and class templates with type packs. - [cpsc-keyword-call(7)](keyword/cpsc-keyword-call.7.md): invoke a procedure. - [cpsc-keyword-openfile(7)](keyword/cpsc-keyword-openfile.7.md): open a text file. diff --git a/doc/language/function/cpsc-function-num_to_str.7.md b/doc/language/function/cpsc-function-num_to_str.7.md index 8e895ee..9d9c071 100644 --- a/doc/language/function/cpsc-function-num_to_str.7.md +++ b/doc/language/function/cpsc-function-num_to_str.7.md @@ -7,13 +7,16 @@ cpsc-function-num_to_str - convert a number to text # SYNOPSIS ```text -NUM_TO_STR(number : INTEGER or REAL) RETURNS STRING +NUM_TO_STR(number : INTEGER or REAL) RETURNS DEFAULT STRING +NUM_TO_STR(number : INTEGER or REAL) RETURNS CHAR ``` # DESCRIPTION Provided by the standard string library, loaded and linked by default. +The function table in the 9618 winter 2025 insert allows INTEGER or REAL input and STRING or CHAR output. Context selects the result type; the compiler's DEFAULT extension selects STRING when context supplies none. CHAR results use the same formatting as STRING results and must contain exactly one character, otherwise a catchable runtime error is raised. Thus INTEGER 7 can return '7', but INTEGER 12 and REAL 7.0 cannot return CHAR. + Format INTEGER as signed decimal text and REAL in the same shortest round-trip form that OUTPUT prints. The text is the shortest decimal text that reads back as the same value (as Python's `repr`): fixed notation with at least one fractional digit when 1e-4 <= |x| < 1e16 (`2.0`, `87.5`, `0.0001`), otherwise scientific notation with an exponent of at least two digits (`1e-07`, `1.5e-07`, `1e+16`); special values print as `-0.0`, `inf`, `-inf` and `nan`. # EXAMPLE @@ -24,4 +27,4 @@ OUTPUT NUM_TO_STR(42), " ", NUM_TO_STR(3.5) # SEE ALSO -[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md). +[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-default(7)](../keyword/cpsc-keyword-default.7.md), [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md). diff --git a/doc/language/function/cpsc-function-str_to_num.7.md b/doc/language/function/cpsc-function-str_to_num.7.md index a9d008b..6351ec9 100644 --- a/doc/language/function/cpsc-function-str_to_num.7.md +++ b/doc/language/function/cpsc-function-str_to_num.7.md @@ -2,20 +2,24 @@ # NAME -cpsc-function-str_to_num - convert text to a real number +cpsc-function-str_to_num - convert text to a number # SYNOPSIS ```text -STR_TO_NUM(text : STRING) RETURNS REAL -STR_TO_NUM(text : CHAR) RETURNS REAL +STR_TO_NUM(text : STRING) RETURNS DEFAULT REAL +STR_TO_NUM(text : CHAR) RETURNS DEFAULT REAL +STR_TO_NUM(text : STRING) RETURNS INTEGER +STR_TO_NUM(text : CHAR) RETURNS INTEGER ``` # DESCRIPTION Provided by the standard string library, loaded and linked by default. -Return REAL, including for integer-looking text. The whole string must be consumed. Invalid text and trailing junk throw a catchable exception reading `STR_TO_NUM: '' is not a number`, and overflowing values throw `STR_TO_NUM: '' is out of the REAL range`. Underflow is accepted. Use IS_NUM first to check numeric text without throwing for invalid input. +The function table in the 9618 winter 2025 insert allows STRING or CHAR input and REAL or INTEGER output. The compiler selects the return type from context and defaults to REAL, including for integer-looking text. The INTEGER version parses as REAL and applies INT, truncating toward zero with the existing INTEGER range check; it inherits REAL rounding. For example, assigning STR_TO_NUM("-23.45") to an INTEGER gives -23. DEFAULT selection and this truncation policy are compiler extensions. + +The whole string must be consumed. Invalid text and trailing junk throw a catchable exception reading `STR_TO_NUM: '' is not a number`, and REAL overflow throws `STR_TO_NUM: '' is out of the REAL range`. Underflow is accepted. INTEGER overflow uses INT's range error. Use IS_NUM first to check numeric text without throwing for invalid input; it does not check INTEGER range. # EXAMPLE @@ -25,4 +29,4 @@ OUTPUT STR_TO_NUM("12.5") # SEE ALSO -[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-is_num(7)](cpsc-function-is_num.7.md), [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md). +[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-default(7)](../keyword/cpsc-keyword-default.7.md), [cpsc-function-int(7)](cpsc-function-int.7.md), [cpsc-function-is_num(7)](cpsc-function-is_num.7.md), [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md). diff --git a/doc/language/keyword/cpsc-keyword-default.7.md b/doc/language/keyword/cpsc-keyword-default.7.md new file mode 100644 index 0000000..0e9ed9b --- /dev/null +++ b/doc/language/keyword/cpsc-keyword-default.7.md @@ -0,0 +1,42 @@ +% CPSC-KEYWORD-DEFAULT(7) + +# NAME + +cpsc-keyword-default - select a default return type for an overload + +# SYNOPSIS + +```text +OVERLOAD FUNCTION name(parameters) RETURNS DEFAULT type + statements +ENDFUNCTION +``` + +# DESCRIPTION + +DEFAULT is a reserved compiler extension, absent from the CIE guide. Place it between RETURNS and the result type on a non-VOID OVERLOAD FUNCTION. Global functions, class methods and operator functions support it. Templates, including methods of class templates, do not support DEFAULT returns. + +When the surrounding context requires a result type, selection still requires that exact return type. Without a required result type, a unique parameter match is selected normally; if matches differ only by return type, the DEFAULT version is selected. Without a default, such a call remains ambiguous. A cast first prefers its target return type, then may select the default and convert its result. DEFAULT does not resolve competing parameter signatures or global/member operator ties. + +Each case-insensitive name and canonical parameter signature may have at most one DEFAULT return, including across separate input files. Parameter count, types and array rank distinguish these groups; BYREF/BYVAL and array bounds do not. Different parameter signatures may each have a default. Defaults participate only when visible to the caller, and ordinary access checks still apply after selection. + +The standard library marks STR_TO_NUM's REAL results and NUM_TO_STR's STRING results as defaults. Their other return types are selected by context. + +# EXAMPLE + +```text +OVERLOAD FUNCTION Score(Value : INTEGER) RETURNS DEFAULT REAL + RETURN 2.5 +ENDFUNCTION +OVERLOAD FUNCTION Score(Value : INTEGER) RETURNS INTEGER + RETURN 3 +ENDFUNCTION +OUTPUT Score(1) // 2.5 +DECLARE Number : INTEGER +Number <- Score(1) +OUTPUT Number // 3 +``` + +# SEE ALSO + +[cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-operator(7)](cpsc-keyword-operator.7.md), [cpsc-function-str_to_num(7)](../function/cpsc-function-str_to_num.7.md), [cpsc-function-num_to_str(7)](../function/cpsc-function-num_to_str.7.md). diff --git a/doc/language/keyword/cpsc-keyword-function.7.md b/doc/language/keyword/cpsc-keyword-function.7.md index 8a5e37b..fbeb15b 100644 --- a/doc/language/keyword/cpsc-keyword-function.7.md +++ b/doc/language/keyword/cpsc-keyword-function.7.md @@ -25,7 +25,7 @@ A FUNCTION inside CLASS defines a member function, called as `Object.Method(argu As a compiler extension, a top-level `FUNCTION MAIN RETURNS INTEGER` with no parameters supplies the program entry point. MAIN is case insensitive and cannot coexist with top-level executable statements in any input file. Its INTEGER result, truncated to 32 bits, is returned as the process exit status. An uncaught exception prints the generic termination message and returns 1. A PROCEDURE MAIN or a MAIN with parameters or a non-INTEGER result is an error. The usual default INTEGER result type also applies when RETURNS is omitted. -Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types. Calls then require exact argument types and, where the surrounding context requires a result type, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types. Calls then require exact argument types and, where the surrounding context requires a result type, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). `RETURNS DEFAULT type` marks the result to select when context cannot choose among return-only overloads; see [cpsc-keyword-default(7)](cpsc-keyword-default.7.md). # EXAMPLE diff --git a/doc/language/keyword/cpsc-keyword-operator.7.md b/doc/language/keyword/cpsc-keyword-operator.7.md index e18a5e5..6c29370 100644 --- a/doc/language/keyword/cpsc-keyword-operator.7.md +++ b/doc/language/keyword/cpsc-keyword-operator.7.md @@ -31,7 +31,7 @@ Binary operators are `+ - * / DIV MOD & = <> < <= > >= AND OR`. Unary operators Operands match exact static types, without implicit conversions, following OVERLOAD rules. For example, an INTEGER operand does not match a REAL parameter. Visible global definitions and methods of the left operand's class participate together. The selected method must be accessible: PRIVATE never causes a public fallback. Included units provide operators using the ordinary INCLUDE visibility rules. -Return types also distinguish operator overloads. When the context requires a result type (assignment, RETURN, condition, CASE comparison, subscript and similar positions), only definitions returning exactly that type match; if the operands match but no result does, the error is `No matching overload for OPERATOR +(T, U) returning R`. A cast `(R) expr` only prefers R and otherwise selects by operands before converting. Without an expected result type, such as OUTPUT or an operand of another operator, a unique operand match is selected and definitions that differ only by return type are ambiguous. +Return types also distinguish operator overloads. When the context requires a result type (assignment, RETURN, condition, CASE comparison, subscript and similar positions), only definitions returning exactly that type match; if the operands match but no result does, the error is `No matching overload for OPERATOR +(T, U) returning R`. A cast `(R) expr` only prefers R and otherwise selects by operands before converting. Without an expected result type, such as OUTPUT or an operand of another operator, a unique operand match is selected; definitions that differ only by return type need a `RETURNS DEFAULT type` declaration to avoid ambiguity. DEFAULT follows the same rules as ordinary functions and does not resolve global/member operator ties; see [cpsc-keyword-default(7)](cpsc-keyword-default.7.md). The expression has the selected function's declared return type. Comparisons and logic may return any supported function result type: a comparison returning STRING can be printed or assigned to STRING, but a BOOLEAN context requires an overload returning BOOLEAN. CASE comparisons follow the same result-type rule and must return BOOLEAN. A VOID result may be discarded through an explicit call but cannot be used as a value. diff --git a/doc/language/keyword/cpsc-keyword-overload.7.md b/doc/language/keyword/cpsc-keyword-overload.7.md index 2e2a101..1f7a0a4 100644 --- a/doc/language/keyword/cpsc-keyword-overload.7.md +++ b/doc/language/keyword/cpsc-keyword-overload.7.md @@ -24,13 +24,13 @@ ENDCLASS OVERLOAD is a compiler extension, absent from the CIE guide. Put it immediately before FUNCTION or PROCEDURE, after PUBLIC or PRIVATE when an access keyword is present. OVERLOAD is reserved. Every definition sharing a case-insensitive name must specify OVERLOAD. Global functions, procedures, class methods and NEW constructors support it; MAIN and built-in functions do not. -Signatures differ by parameter count, parameter types, array rank, or return type. BYREF versus BYVAL and declared array bounds do not distinguish signatures. A PROCEDURE counts as returning VOID, so it can coexist with a FUNCTION having the same parameter list; a call that cannot determine a result type is then ambiguous. Nominal user types remain distinct; equivalent native C type aliases identify the same type. +Signatures differ by parameter count, parameter types, array rank, or return type. BYREF versus BYVAL and declared array bounds do not distinguish signatures. A PROCEDURE counts as returning VOID, so it can coexist with a FUNCTION having the same parameter list; a call that cannot determine a result type is then ambiguous unless the function specifies a DEFAULT return. Nominal user types remain distinct; equivalent native C type aliases identify the same type. Calls require an exact match to the arguments' static types. No implicit conversion is used to select an overload, even when only one OVERLOAD definition exists. Array arguments must be whole array variables with matching element types and rank. After selection, ordinary parameter-mode, array-bound and access checks apply. Functions without OVERLOAD retain their ordinary argument conversions and their implicit result conversions. When the context requires a known result type, the selected overload must return exactly that type. This applies to assignment targets, BYVAL arguments, RETURN values, conditions, FOR bounds, subscripts and CASE comparisons. If the arguments match but no overload returns the required type, the error is `No matching overload for Name(T1, T2) returning T`. A cast `(T) expr` is weaker: it first prefers an overload returning T, then uses ordinary parameter selection and converts the result to T. -Without an expected result type (for example OUTPUT, an operand of another operator or comparison, a CASE selector, a CALL statement, or an argument passed to another OVERLOAD call), a unique parameter match is selected. If several candidates share the same parameter list and differ only by return type, the call is ambiguous. +Without an expected result type (for example OUTPUT, an operand of another operator or comparison, a CASE selector, a CALL statement, or an argument passed to another OVERLOAD call), a unique parameter match is selected. If several candidates share the same parameter list and differ only by return type, select the one marked `RETURNS DEFAULT type`; without a default, the call is ambiguous. Each name and canonical parameter signature may have only one default, including across input files. DEFAULT does not resolve parameter ambiguity or override a required result type; see [cpsc-keyword-default(7)](cpsc-keyword-default.7.md). Overloads may be defined in separate input files. A caller sees only its own and included units' definitions. Duplicate signatures fail across all inputs, even when neither unit includes the other; two definitions are duplicates only when both their parameters and their return types match. See [cpsc-keyword-include(7)](cpsc-keyword-include.7.md). @@ -53,4 +53,4 @@ OUTPUT Area(2.0) # SEE ALSO -[cpsc-keyword-template(7)](cpsc-keyword-template.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md). +[cpsc-keyword-default(7)](cpsc-keyword-default.7.md), [cpsc-keyword-template(7)](cpsc-keyword-template.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md). diff --git a/doc/language/keyword/cpsc-keyword-procedure.7.md b/doc/language/keyword/cpsc-keyword-procedure.7.md index 2b251b5..30946e1 100644 --- a/doc/language/keyword/cpsc-keyword-procedure.7.md +++ b/doc/language/keyword/cpsc-keyword-procedure.7.md @@ -20,7 +20,7 @@ Arrays accept `ARRAY OF type` or `ARRAY[lower:upper, ...] OF type`; explicit bou A PROCEDURE inside CLASS defines a member procedure, called as `Object.Method(arguments)` or `CALL Object.Method(arguments)`. It follows the same parameter rules and modifies the receiver. Within a method, `this` refers directly to the current object; see [cpsc-keyword-class(7)](cpsc-keyword-class.7.md). -Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types; a procedure counts as returning VOID. A CALL statement has no expected result type, so a procedure and a function with the same parameters are ambiguous there. Other calls require exact argument types and, when a result type is required, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types; a procedure counts as returning VOID. A CALL statement has no expected result type, so a procedure and a function with the same parameters are ambiguous there unless the function has a DEFAULT return. Other calls require exact argument types and, when a result type is required, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). # EXAMPLE diff --git a/doc/language/keyword/cpsc-keyword-template.7.md b/doc/language/keyword/cpsc-keyword-template.7.md index ca158c8..afa9cba 100644 --- a/doc/language/keyword/cpsc-keyword-template.7.md +++ b/doc/language/keyword/cpsc-keyword-template.7.md @@ -33,7 +33,7 @@ When multiple function or procedure definitions share a name, every definition, Use a class instance such as `Box` wherever a type name is accepted, including nested instances such as `Box>`. Supply all class type arguments explicitly; variadic CLASS templates are allowed, and their methods may use the class's pack parameters. Pack fields such as `Values : Rest...` are rejected. Constructors, ownership and destruction follow ordinary CLASS rules. In particular, a declaration without constructor arguments needs a matching parameterless NEW when constructors exist; see [cpsc-keyword-class(7)](cpsc-keyword-class.7.md). -Non-type parameters, SIZEOF..., member templates, operator templates, specialization and pointer-alias templates are unsupported. Within a class template, write the full instance type rather than the bare class name. Pointer-linked generic containers remain unsupported because pointer-alias templates are unavailable. +Non-type parameters, SIZEOF..., member templates, operator templates, specialization and pointer-alias templates are unsupported. DEFAULT return declarations are also unsupported in templates, including methods of class templates. Within a class template, write the full instance type rather than the bare class name. Pointer-linked generic containers remain unsupported because pointer-alias templates are unavailable. Source template lists cannot be empty: `<>` is the inequality token. Nested closing `>>` works as two tokens. Separate `<` from a following `-` and `>` from a following `=` to avoid the `<-` and `>=` tokens. Expression lookahead treats `A < B, C > (D)` as a template call; parenthesize comparisons to avoid this ambiguity. -- cgit v1.3.1-4-g156e