fix: BoxedSymbol property computations (various)

- Fixes the return value of 'sgn' for BoxedNumbers with a value of 'NaN': as a corollary fixes & now correctly computes return-value of getter `BoxedSymbol.isNaN`, too. - Fix: for consistency, 'isNaN' & 'isInfinity' now trigger definition binding (canonicalization), in similar manner to 'isOdd', 'isEven', 'isInteger'... (This is appropriate because these may be considered direct 'value inquiry' getters, similarly to these sibling properties) - Adds missing getter 'isFinite': computing the result using 'sgn' like its sign-checking siblings 'isPositive', 'isNegative'... - Fix: several properties/getters now return a boolean in cases where 'undefined' should be returned (because, the symbol is unbound and therefore not enough information is known). ^Notably, this is restricted to the aforementioned - 'sgn' referencing - properties 'is(NaN/Infinity)' et cetera. - Fix: revise getter 'isInfinity' to now account for 'complex-infinity' Also includes various extra doc., including some corrections

Author: samueltlg

src/compute-engine/boxed-expression/boxed-number.ts

@@ -364,7 +364,7 @@ export class BoxedNumber extends _BoxedExpression {
 
  let s: number | undefined;
  if (typeof this._value === 'number') {
- if (Number.isNaN(this._value)) return 'unsigned';
+ if (Number.isNaN(this._value)) return 'nan';
  s = Math.sign(this._value);
  } else s = this._value.sgn();
  // The sign of a complex Numeric Value is `undefined`

src/compute-engine/boxed-expression/boxed-symbol.ts

@@ -50,6 +50,7 @@ import {
  nonPositiveSign,
  negativeSign,
  nonNegativeSign,
+ infinitySgn,
 } from './sgn';
 import type { BigNum } from '../numerics/types';
 import type { OneOf } from '../../common/one-of';
@@ -68,27 +69,47 @@ import { BoxedType } from '../../common/type/boxed-type';
  * not a function expression, i.e. `Sin`, not `["Sin", "Pi"]`. This is used
  * for example in `["InverseFunction", "Sin"]`
  *
+ * BoxedSymbols are bound *lazily* to a definition: unless constructed with either 'canonical =
+ * true' or a definition is explicitly given.
+ *
+ * Various, predicate-based properties & getters for this class either:
+ *
+ * - Trigger the symbol to be bound (if not already). This encompasses those properties that
+ * imply, or rely on accessing the symbol definition - including its value or type. Included are:
+ * 'value', 'isOdd/Even', 're', 'im', or 'isReal/Rational': amongst others.
+ *
+ * - Do not trigger the symbol to be bound, but nevertheless require this to be the case to return
+ * an effective value.
+ * These properties typically return with type `boolean | undefined`, and spans those such as
+ * 'isNaN', 'isInfinity' 'isPositive' & 'isNegative'.
+ * Notably, this is the case for properties which relate to a *range* of values or 'assumptions'
+ * about the symbol (e.g. 'is..Positive/Negative'); or in which looking up the value directly is
+ * not necessary to compute the result (e.g. 'isFinite').
+ *
+ *
+ * Methods which require consultation to a definition value also trigger binding: comparison methods
+ * ('is', 'isSame', 'isEqual', 'isLess'...), 'evaluate' & 'N', and methods pertinent to
+ * 'collection'-valued symbols such as 'contains' & 'subsetOf'.
+ *
  *
  */
 export class BoxedSymbol extends _BoxedExpression {
  private _scope: RuntimeScope | null;
  protected _id: string;
  private _hash: number | undefined;
 
- // Note: a `BoxedSymbol` is bound lazily to a definition. This is important
- // during the creation of a scope to avoid circular references.
+ // Note: a `BoxedSymbol` is bound lazily to a definition: unless constructed canonically, or with
+ // a given/explicit definition. This is important during the creation of a scope to avoid
+ // circular references.
  //
  // This can also happen if a symbol is used before being defined
  // and the engine has no default domain specified. If there
  // is a default domain, a definition is created automatically.
 
- // `undefined` indicate the symbol has not been bound yet,
- // `null` indicate that the symbol is not canonical and it should not be
- // bound.
+ // `undefined` indicates that the symbol has not been bound yet
 
  private _def:
  | OneOf<[BoxedSymbolDefinition, BoxedFunctionDefinition]>
- | null
  | undefined;
 
  private _isStructural: boolean = false;
@@ -114,6 +135,7 @@ export class BoxedSymbol extends _BoxedExpression {
 
  if (options?.structural) this._isStructural = true;
 
+ //(A symbol having a _scope is indicator of it being canonical)
  if ((options?.canonical ?? true) !== true) this._scope = null;
  else if (this._def) this._scope = ce.context;
  else this.bind();
@@ -165,7 +187,13 @@ export class BoxedSymbol extends _BoxedExpression {
  return ce.lookupSymbol(this._id) ?? ce.lookupFunction(this._id);
  }
 
- /** This method returns the definition associated with the value of this symbol, or associated with the symbol if it has no value. This is the definition to use with most operations on the symbol. Indeed, "x[2]" is accessing the second element of **the value** of "x".*/
+ /** This method returns the definition associated with the value of this symbol, or associated with
+ * the symbol if it has no value. Used primarily to check, or obtain the value definition for, the
+ * case where this symbol has a 'collection' definition
+ *
+ * This is the definition to use with most operations on the symbol. Indeed, "x[2]" is accessing
+ * the second element of **the value** of "x".
+ */
  private _getDef(): BoxedBaseDefinition | undefined {
  let def: BoxedBaseDefinition | BoxedSymbolDefinition | undefined =
  this.symbolDefinition;
@@ -500,7 +528,7 @@ export class BoxedSymbol extends _BoxedExpression {
  }
 
  // The type of the value of the symbol.
- // If the symbol is not bound to a definition, the type is 'any'
+ // If the symbol is not bound to a definition, the type is 'unknown'
  get type(): BoxedType {
  const def = this._def;
  if (!def) return BoxedType.unknown;
@@ -555,6 +583,9 @@ export class BoxedSymbol extends _BoxedExpression {
  return match(this, pattern, options);
  }
 
+ /**
+ * **Note**: This check _binds_ the symbol.
+ */
  get isFunction(): boolean | undefined {
  return !!this.functionDefinition;
  }
@@ -567,14 +598,18 @@ export class BoxedSymbol extends _BoxedExpression {
  return this.symbolDefinition?.even;
  }
 
- get isInfinity(): boolean | undefined {
+ get isFinite(): boolean | undefined {
  const s = this.sgn;
- return s === 'negative-infinity' || s === 'positive-infinity';
+ if (!s) return undefined;
+ return !(infinitySgn(s) || s === 'nan');
+ }
+
+ get isInfinity(): boolean | undefined {
+ return infinitySgn(this.symbolDefinition?.sgn);
  }
 
  get isNaN(): boolean | undefined {
- const s = this.sgn;
- return s === 'nan';
+ return this.symbolDefinition?.sgn === 'nan';
  }
 
  // x > 0
@@ -594,6 +629,12 @@ export class BoxedSymbol extends _BoxedExpression {
  return nonNegativeSign(this.sgn);
  }
 
+ /**
+ *
+ * Checking this does *not bind* the definition if this is symbol.
+ *
+ * @inheritdoc
+ */
  get isNumber(): boolean | undefined {
  // Since we infer the type of a symbol to a `number`, we don't need
  // to check if the type was inferred.

src/compute-engine/boxed-expression/sgn.ts

@@ -35,6 +35,15 @@ export function sgn(expr: BoxedExpression): Sign | undefined {
  return 'unsigned';
 }
 
+export function infinitySgn(s: Sign | undefined): boolean | undefined {
+ if (s === undefined) return undefined;
+ return (
+ s === 'positive-infinity' ||
+ s === 'negative-infinity' ||
+ s === 'complex-infinity'
+ );
+}
+
 // > 0
 export function positiveSign(s: Sign | undefined): boolean | undefined {
  if (s === undefined) return undefined;

src/compute-engine/global-types.ts

@@ -26,21 +26,21 @@ import type {
  MathJsonFunction,
  MathJsonIdentifier,
 } from '../math-json';
-import {
+import type {
  LatexDictionaryEntry,
  LatexString,
  ParseLatexOptions,
  SerializeLatexOptions,
 } from './latex-syntax/types';
-import {
+import type {
  ExactNumericValueData,
  NumericValue,
  NumericValueData,
 } from './numeric-value/types';
-import { BigNum, IBigNum, Rational } from './numerics/types';
-import { Type, TypeString } from '../common/type/types';
-import { BoxedType } from '../common/type/boxed-type';
-import { IndexedLatexDictionary } from './latex-syntax/dictionary/definitions';
+import type { BigNum, IBigNum, Rational } from './numerics/types';
+import type { Type, TypeString } from '../common/type/types';
+import type { BoxedType } from '../common/type/boxed-type';
+import type { IndexedLatexDictionary } from './latex-syntax/dictionary/definitions';
 
 /** @category Compiling */
 export type CompiledType = boolean | number | string | object;
@@ -711,13 +711,17 @@ export interface BoxedExpression {
  * Note that if `isNaN` is true, `isNumber` is also true (yes, `NaN` is a
  * number).
  *
+ * If this expression is a symbol, this lookup also causes binding to a definition.
+ *
  * @category Numeric Expression
  *
  */
  readonly isNaN: boolean | undefined;
 
  /**
- * The numeric value of this expression is `±Infinity` or Complex Infinity
+ * The numeric value of this expression is `±Infinity` or Complex Infinity.
+ *
+ * If this is a symbol, causes it to be bound to a definition.
  *
  * @category Numeric Expression
  */
@@ -901,6 +905,9 @@ export interface BoxedExpression {
  * will return `positive` if the symbol is assumed to be positive
  * (using `ce.assume()`).
  *
+ * For a symbol also, requires that the symbol be bound with its definition (i.e. canonical);
+ * otherwise, will return `undefined`.
+ *
  * @category Numeric Expression
  *
  */
@@ -1010,7 +1017,8 @@ export interface BoxedExpression {
  * definition.
  *
  * :::info[Note]
- * `undefined` if not a canonical expression.
+ * For a symbol, always binds - potentially creating - a definition. For `BoxedFunctions`, will
+ * return `undefined` if not canonical.
  * :::
  *
  */
@@ -1029,6 +1037,8 @@ export interface BoxedExpression {
  /**
  * For symbols, a definition associated with the expression.
  *
+ * Bind the expression to a definition, if not already bound.
+ *
  * Return `undefined` if not a symbol
  *
  */
@@ -1205,14 +1215,13 @@ export interface BoxedExpression {
  get value(): number | boolean | string | object | undefined;
 
  /**
- * Only the value of variables can be changed (symbols that are not
- * constants).
+ * Set the value of this expression (applicable only to `BoxedSymbol`).
  *
- * Throws a runtime error if a constant.
+ * Will throw a runtime error if either not a BoxedSymbol, or if a symbol expression which is
+ * non-variable/constant.
  *
- * :::info[Note]
- * If non-canonical, does nothing
- * :::
+ * Setting the value of a symbol results in the forgetting of all assumptions about it in the
+ * current scope.
  *
  */
  set value(
@@ -1241,6 +1250,7 @@ export interface BoxedExpression {
  * If not valid, return `"error"`.
  * If non-canonical, return `undefined`.
  * If the type is not known, return `"unknown"`.
+ * If a symbol with a 'function' definition, returns the 'signature' type.
  * :::
  *
  */
@@ -1336,7 +1346,10 @@ export interface BoxedExpression {
  isEqual(other: number | BoxedExpression): boolean | undefined;
 
  /**
- * Return true if the expression is a collection: a list, a vector, a matrix, a map, a tuple, etc...
+ * Return true if the expression is a collection: a list, a vector, a matrix, a map, a tuple,
+ * etc...
+ *
+ * For symbols, this check involves binding to a definition, if not already canonical.
  */
  isCollection: boolean;
 

src/compute-engine/index.ts

@@ -2175,7 +2175,7 @@ export class ComputeEngine implements IComputeEngine {
  }
  }
 
- /** Remove all assumptions about one or more symbols */
+ /** Remove all assumptions (in the current scope) about one or more symbols */
  forget(symbol: undefined | string | string[]): void {
  if (!this.context) throw Error('No scope available');
 

test/compute-engine/numbers.test.ts

@@ -1,5 +1,5 @@
-import { BoxedExpression } from '../../src/compute-engine.ts';
 import { Expression } from '../../src/math-json/types.ts';
+import type { BoxedExpression } from '../../src/compute-engine/global-types.ts';
 import { engine as ce } from '../utils';
 
 describe('BOXING OF NUMBER', () => {
@@ -198,7 +198,7 @@ describe('PROPERTIES OF NUMBERS', () => {
  -1: false
  0: false
  +1: false
- finite: undefined
+ finite: true
  infinite: false
  nan: false
  even: undefined
@@ -374,7 +374,7 @@ describe('PROPERTIES OF NUMBERS', () => {
  -1: false
  0: false
  +1: false
- finite: undefined
+ finite: true
  infinite: false
  nan: false
  even: undefined