From 69ec9a1ab7fed3293bae642279b270b9e5c08255 Mon Sep 17 00:00:00 2001 From: David de Hilster Date: Sun, 26 Jul 2026 08:51:29 -0400 Subject: [PATCH] docs(help): document the new NLP++ math functions Adds help pages for the math functions introduced in nlp-engine#699: floor round down, toward -infinity ceiling round up, toward +infinity round nearest whole number, halfway away from zero truncate discard the fraction, toward zero sqrt square root pow raise a number to a power log natural (base e) logarithm Each page follows the existing math-page shape (Purpose / Syntax / Returns / Remarks / Example / See Also), cross-linked so the four rounding functions point at each other and the power and log functions point at logten. The floor and truncate pages spell out where they diverge on negatives, since that is the easy thing to get wrong. Table_of_Math_Functions.md gains the seven rows in alphabetical order, and index.md lists the new pages under Math Functions. check-help-docs.ps1 against c:\git\nlp-engine\lite: 0 broken links, 0 broken images, 0 table/index drift, and the seven names no longer appear under "engine names with no help page". Note: the examples avoid negative literals. Passing one directly, as the existing abs page does with abs(-7), does not currently parse in NLP++. Co-Authored-By: Claude Opus 5 (1M context) --- Help/markdown/Table_of_Math_Functions.md | 7 ++++ Help/markdown/ceiling.md | 51 +++++++++++++++++++++++ Help/markdown/floor.md | 51 +++++++++++++++++++++++ Help/markdown/index.md | 7 ++++ Help/markdown/log.md | 51 +++++++++++++++++++++++ Help/markdown/pow.md | 53 ++++++++++++++++++++++++ Help/markdown/round.md | 51 +++++++++++++++++++++++ Help/markdown/sqrt.md | 51 +++++++++++++++++++++++ Help/markdown/truncate.md | 51 +++++++++++++++++++++++ 9 files changed, 373 insertions(+) create mode 100644 Help/markdown/ceiling.md create mode 100644 Help/markdown/floor.md create mode 100644 Help/markdown/log.md create mode 100644 Help/markdown/pow.md create mode 100644 Help/markdown/round.md create mode 100644 Help/markdown/sqrt.md create mode 100644 Help/markdown/truncate.md diff --git a/Help/markdown/Table_of_Math_Functions.md b/Help/markdown/Table_of_Math_Functions.md index a84f55e..7dd4cda 100644 --- a/Help/markdown/Table_of_Math_Functions.md +++ b/Help/markdown/Table_of_Math_Functions.md @@ -7,10 +7,17 @@ NLP++ now features mathematical functions analogous to those provided in C/C++. | **FUNCTION NAME** | **RETURNS** | **DESCRIPTION** | | --- | --- | --- | | [**abs(num_int)**](abs.md) | **INT** | Get the absolute value of a given integer. | +| [**ceiling(num_float)**](ceiling.md) | **INT** | Round a number up to the nearest whole number. Analogous to the ceil function in C/C++. | | [**factorial(num_int)**](factorial.md) | **INT** | Get the factorial of a non-negative integer. | +| [**floor(num_float)**](floor.md) | **INT** | Round a number down to the nearest whole number. Analogous to the floor function in C/C++. | +| [**log(num_float)**](log.md) | **FLOAT** | Get the natural (base e) logarithm of a number. Analogous to the log function in C/C++. | | [**logten(num_float)**](logten.md) | **FLOAT** | Get base 10 logarithm of given number. Analogous to log10 function in C/C++. | | [**mod(num_int1, num_int2)**](mod.md) | **INT** | Get the remainder of dividing one integer by another. | +| [**pow(base_float, exponent_float)**](pow.md) | **FLOAT** | Raise a number to the given power. Analogous to the pow function in C/C++. | | [**randomint(num_int1, num_int2)**](randomint.md) | **INT** | Get a random integer between two given integers, inclusive. | +| [**round(num_float)**](round.md) | **INT** | Round a number to the nearest whole number, with halfway cases rounding away from zero. Analogous to the round function in C/C++. | +| [**sqrt(num_float)**](sqrt.md) | **FLOAT** | Get the square root of a number. Analogous to the sqrt function in C/C++. | +| [**truncate(num_float)**](truncate.md) | **INT** | Discard the fractional part of a number, rounding toward zero. Analogous to the trunc function in C/C++. | | | | | ## See Also diff --git a/Help/markdown/ceiling.md b/Help/markdown/ceiling.md new file mode 100644 index 0000000..38fc2c2 --- /dev/null +++ b/Help/markdown/ceiling.md @@ -0,0 +1,51 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# ceiling + +## Purpose + +Round a number up to the nearest whole number. + +## Syntax + +``` +returnedInt = ceiling(numFlt) +``` + +``` +returnedInt - type: int + +numFlt - type: float +``` + +## Returns + +The smallest whole number that is greater than or equal to the given number. + +## Remarks + +Analogous to the ceil function in C/C++. Rounds toward positive infinity, so the ceiling of a negative number moves toward zero: the ceiling of -3.7 is -3. + +## Example + +``` +@CODE + +"output.txt" << ceiling(3.2) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +4 +``` + +## See Also + +[floor](floor.md), [ceiling](ceiling.md), [round](round.md), [truncate](truncate.md) + +[Math Functions](Table_of_Math_Functions.md) diff --git a/Help/markdown/floor.md b/Help/markdown/floor.md new file mode 100644 index 0000000..e57d953 --- /dev/null +++ b/Help/markdown/floor.md @@ -0,0 +1,51 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# floor + +## Purpose + +Round a number down to the nearest whole number. + +## Syntax + +``` +returnedInt = floor(numFlt) +``` + +``` +returnedInt - type: int + +numFlt - type: float +``` + +## Returns + +The largest whole number that is less than or equal to the given number. + +## Remarks + +Analogous to the floor function in C/C++. Rounds toward negative infinity, so the floor of a negative number moves away from zero: the floor of -3.7 is -4. Use [truncate](truncate.md) to discard the fraction and round toward zero instead. + +## Example + +``` +@CODE + +"output.txt" << floor(3.7) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +3 +``` + +## See Also + +[floor](floor.md), [ceiling](ceiling.md), [round](round.md), [truncate](truncate.md) + +[Math Functions](Table_of_Math_Functions.md) diff --git a/Help/markdown/index.md b/Help/markdown/index.md index 94eb0f3..e86cbec 100644 --- a/Help/markdown/index.md +++ b/Help/markdown/index.md @@ -372,10 +372,17 @@ to a topic. - **Math Functions** - [Table of Math Functions](Table_of_Math_Functions.md) - [abs](abs.md) + - [ceiling](ceiling.md) - [factorial](factorial.md) + - [floor](floor.md) + - [log](log.md) - [logten](logten.md) - [mod](mod.md) + - [pow](pow.md) - [randomint](randomint.md) + - [round](round.md) + - [sqrt](sqrt.md) + - [truncate](truncate.md) - [Parse Tree Functions](Table_of_Parse_Tree_Functions.md) - [Table of Parse Tree Functions](Table_of_Parse_Tree_Functions.md) - [arraylength](arraylength.md) diff --git a/Help/markdown/log.md b/Help/markdown/log.md new file mode 100644 index 0000000..c3bf38f --- /dev/null +++ b/Help/markdown/log.md @@ -0,0 +1,51 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# log + +## Purpose + +Compute the natural (base e) logarithm of a number. + +## Syntax + +``` +returnedFlt = log(numFlt) +``` + +``` +returnedFlt - type: float + +numFlt - type: float +``` + +## Returns + +The natural logarithm of the given number. + +## Remarks + +Analogous to the log function in C/C++. The argument must be positive. See [logten](logten.md) for the base 10 logarithm. + +## Example + +``` +@CODE + +"output.txt" << log(2.718282) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +1 +``` + +## See Also + +[sqrt](sqrt.md), [pow](pow.md), [log](log.md), [logten](logten.md) + +[Math Functions](Table_of_Math_Functions.md) diff --git a/Help/markdown/pow.md b/Help/markdown/pow.md new file mode 100644 index 0000000..12cc2d8 --- /dev/null +++ b/Help/markdown/pow.md @@ -0,0 +1,53 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# pow + +## Purpose + +Raise a number to the given power. + +## Syntax + +``` +returnedFlt = pow(baseFlt,exponentFlt) +``` + +``` +returnedFlt - type: float + +baseFlt - type: float + +exponentFlt - type: float +``` + +## Returns + +The base raised to the power of the exponent. + +## Remarks + +Analogous to the pow function in C/C++. A negative base with a fractional exponent is undefined, and a result outside the range of a float is an error. + +## Example + +``` +@CODE + +"output.txt" << pow(2,10) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +1024 +``` + +## See Also + +[sqrt](sqrt.md), [pow](pow.md), [log](log.md), [logten](logten.md) + +[Math Functions](Table_of_Math_Functions.md) diff --git a/Help/markdown/round.md b/Help/markdown/round.md new file mode 100644 index 0000000..cbbd283 --- /dev/null +++ b/Help/markdown/round.md @@ -0,0 +1,51 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# round + +## Purpose + +Round a number to the nearest whole number. + +## Syntax + +``` +returnedInt = round(numFlt) +``` + +``` +returnedInt - type: int + +numFlt - type: float +``` + +## Returns + +The whole number nearest the given number. + +## Remarks + +Analogous to the round function in C/C++. Halfway cases round away from zero, so round of 3.5 is 4 and round of -3.5 is -4. + +## Example + +``` +@CODE + +"output.txt" << round(3.5) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +4 +``` + +## See Also + +[floor](floor.md), [ceiling](ceiling.md), [round](round.md), [truncate](truncate.md) + +[Math Functions](Table_of_Math_Functions.md) diff --git a/Help/markdown/sqrt.md b/Help/markdown/sqrt.md new file mode 100644 index 0000000..55e92b5 --- /dev/null +++ b/Help/markdown/sqrt.md @@ -0,0 +1,51 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# sqrt + +## Purpose + +Compute the square root of a number. + +## Syntax + +``` +returnedFlt = sqrt(numFlt) +``` + +``` +returnedFlt - type: float + +numFlt - type: float +``` + +## Returns + +The square root of the given number. + +## Remarks + +Analogous to the sqrt function in C/C++. A negative argument is an error and no value is returned. + +## Example + +``` +@CODE + +"output.txt" << sqrt(16) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +4 +``` + +## See Also + +[sqrt](sqrt.md), [pow](pow.md), [log](log.md), [logten](logten.md) + +[Math Functions](Table_of_Math_Functions.md) diff --git a/Help/markdown/truncate.md b/Help/markdown/truncate.md new file mode 100644 index 0000000..e8ab118 --- /dev/null +++ b/Help/markdown/truncate.md @@ -0,0 +1,51 @@ +[← Help Contents](index.md) | [📘 NLP++ Textbook](NLP++_Textbook.md) + +# truncate + +## Purpose + +Discard the fractional part of a number. + +## Syntax + +``` +returnedInt = truncate(numFlt) +``` + +``` +returnedInt - type: int + +numFlt - type: float +``` + +## Returns + +The given number with its fractional part removed. + +## Remarks + +Analogous to the trunc function in C/C++. Rounds toward zero, so truncate of -3.7 is -3, whereas [floor](floor.md) of -3.7 is -4. + +## Example + +``` +@CODE + +"output.txt" << truncate(3.7) << "\n"; + +@@CODE +``` + +``` +Outputs: +``` + +``` +3 +``` + +## See Also + +[floor](floor.md), [ceiling](ceiling.md), [round](round.md), [truncate](truncate.md) + +[Math Functions](Table_of_Math_Functions.md)