# Primes plugin for Take Command / TCC / TCC/LE

### beta version 0.99.16 2024-01-02

### Charles Dye

#### Purpose:

This plugin provides replacements for TCC’s internal
`@ISPRIME`

and
`@PRIME`

functions, and also provides
a new function `@LPRIME`

to return the
largest prime number not greater than a given value. These functions are
intended to produce correct results across the entire range of 64-bit
unsigned integers.

I also provide some additional functions involving factorization.
`@FACTORS`

returns a list of prime
factors of a given value. `@GCF`

and
`@LCM`

return, respectively, the greatest
common factor and the least common multiple for a set of numbers.
`@ISQRT`

is used internally by the
factorization routines; I expose it in case someone else has a use for
it.

N.B.: I am no mathematician, and my methods are not sophisticated. These functions will be slow for extremely large values of n.

#### Installation:

To use this plugin, copy Primes.dll to
some known location on your hard drive. (If you are still using the 32-bit
version of Take Command, take Primes-x86.dll
instead of Primes.dll.) Load the .DLL file
with a `PLUGIN /L`

command, for example:

`plugin /l c:\bin\tcmd\test\primes.dll`

If you copy the .DLL file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

#### Plugin Features:

New functions: `@FACTORS`

,
`@GCF`

, `@ISPRIME`

,
`@ISQRT`

, `@LCM`

,
`@LPRIME`

, `@PRIME`

#### Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

`BOLD CODE` | indicates text which must be typed exactly as shown. |

`CODE` | indicates optional text, which may be typed as shown or omitted. |

Bold italic | names a required argument; a value must be supplied. |

Regular italic | names an optional argument. |

ellipsis… | after an argument means that more than one may be given. |

#### New Functions:

`@FACTORS`

— Returns a list of
prime factors of a given value.

Syntax:

`%@FACTORS[`

n`,`

m`,`

p`]`

n | a 64-bit unsigned integer |

m | the multiplication symbol (defaults to “` × ` ”) |

p | the power symbol (defaults to none — not used) |

n may be decimal, or hexadecimal with a
leading `0x`

.

m is the multiplication symbol used to separate factors. If you want to include spaces or commas in this string, quote it.

p is the exponentation symbol, used for repeated
factors. If you want to include spaces or commas in this string, quote it. If you
want to use a caret, escape it. If you do not specify a power symbol, `@FACTOR`

will not use exponentation; repeated factors will simply be repeated.

`rem The default behavior:`

echo %@factors[3776]

2 × 2 × 2 × 2 × 2 × 2 × 59

rem Use a different multiplication symbol:

echo %@factors[3776,*]

2*2*2*2*2*2*59

rem Use a caret to show powers:

echo %@factors[3776,,^^]

2^6 × 59

rem C-style character escapes are supported:

echo %@factors[3776,\ub7,\u2191]

2↑6·59

You can also use an expression for the value. If n
does not look like a number, `@FACTORS`

will try to expand it via
Evaluate(), so you can use syntax like:

`echo %@factors[2 ** 16 - 1]`

3 × 5 × 17 × 257

C-style character escapes are supported in both the m and p strings:

`echo %@factors[49152,\x20\xd7\x20,\x2191]`

2↑14 × 3

`@GCF`

— Returns the greatest
common factor of a set of numbers.

Syntax:

`%@GCF[`

n1`,`

n2`,`

…`]`

n1, n2, … | 64-bit unsigned integers; must be > 0 |

You must supply at least one value; you may give as many as 32. Values
may be in decimal, or hexadecimal with a leading `0x`

. All values
must be greater than zero.

`echo %@gcf[1023,2541]`

33

echo %@factors[1023]

3 × 11 × 31

echo %@factors[2541]

3 × 7 × 11 × 11

See also: `@LCM`

, which returns
the least common multiple of a set of numbers.

`@ISPRIME`

— Tests a number for
primeness.

Syntax:

`%@ISPRIME[`

n`]`

n | a 64-bit unsigned integer |

n may be decimal, or hexadecimal with a
leading `0x`

.

Returns `1`

if n has exactly two
factors, `0`

otherwise. (By this definition, zero and one are
*not prime*, so both return `0`

.)

`for /l %i in ( 0, 1, 13 ) echo %i - %@isprime[%i]`

0 - 0

1 - 0

2 - 1

3 - 1

4 - 0

5 - 1

6 - 0

7 - 1

8 - 0

9 - 0

10 - 0

11 - 1

12 - 0

13 - 1

You can also use an expression for the value. If n
does not look like a number, `@ISPRIME`

will try to expand it via
Evaluate(), so you can use syntax like:

`echo %@isprime[2 ** 64 - 59]`

1

`@ISQRT`

— Returns the integer
square root of a number.

Syntax:

`%@ISQRT[`

n`]`

n | a 64-bit unsigned integer |

n may be decimal, or hexadecimal with a
leading `0x`

.

isqrt() is a function used internally by several of this plugin’s functions. I’m exposing it to the user on the off chance that someone might find it useful.

`echo %@isqrt[1024]`

32

echo %@isqrt[1023]

31

You can also use an expression for the value. If n
does not look like a number, `@ISQRT`

will try to expand it via
Evaluate(), so you can use syntax like:

`echo %@isqrt[3 ** 6]`

27

You can append an `=X`

or `=H`

to the value to
return it in hexadecimal, with or without a leading `0x`

:

```
echo %@isqrt[3 ** 6 =X]
```

0x1B

`@LCM`

— Returns the least common
multiple of a set of numbers.

Syntax:

`%@LCM[`

n1`,`

n2`,`

…`]`

n1, n2, … | 64-bit unsigned integers; must be > 0 |

You must supply at least one value; you may give as many as 32. Values
may be in decimal, or hexadecimal with a leading `0x`

. All values
must be greater than zero.

Note that for extremely large values, it is possible for the LCM to
overflow the 64-bit integer range. In this case you will get an error message.
Also, be aware that this function factorizes *every* value that you pass
to it. If you pass several extremely large values, this can take a significant
amount of time!

`echo %@lcm[1023,2541]`

78771

echo %@factors[1023]

3 × 11 × 31

echo %@factors[2541]

3 × 7 × 11 × 11

echo %@eval[3 * 7 * 11 * 11 *31]

78771

See also: `@GCF`

, which returns
the greatest common factor of a set of numbers.

`@LPRIME`

— Returns the largest prime
number not greater than the given value.

Syntax:

`%@LPRIME[`

n`]`

n | a 64-bit unsigned integer; must be ≥ 2 |

n may be decimal, or hexadecimal with a
leading `0x`

.

`echo %@lprime[8192]`

8191

You can also use an expression for the value. If n
does not look like a number, `@LPRIME`

will try to expand it via
Evaluate(), so you can use syntax like:

`echo %@lprime[2 ** 16]`

65521

You can append an `=X`

or `=H`

to the value to
return it in hexadecimal, with or without a leading `0x`

:

```
echo %@lprime[2 ** 16 =X]
```

0xFFF1

See also: `@PRIME`

, which returns the
rightward prime.

`@PRIME`

— Returns the smallest prime
number not less than the given value.

Syntax:

`%@PRIME[`

n`]`

n | a 64-bit unsigned integer |

n may be decimal, or hexadecimal with a
leading `0x`

.

If n is not prime and the next higher prime number is outside the 64-bit range, you’ll get an “integer overflow” error.

`echo %@prime[8192]`

8209

You can also use an expression for the value. If n
does not look like a number, `@PRIME`

will try to expand it via
Evaluate(), so you can use syntax like:

`echo %@prime[2 ** 16]`

65537

You can append an `=X`

or `=H`

to the value to
return it in hexadecimal, with or without a leading `0x`

:

```
echo %@prime[2 ** 16 =X]
```

0x10001

See also: `@LPRIME`

, which returns
the leftward prime.

#### Startup Message:

This plugin displays an informational line when it initializes. The
message will be suppressed in transient or pipe shells. You can disable it
for all shells by defining an environment variable named `NOLOADMSG`

,
for example:

`set /e /u noloadmsg=1`

#### Acknowledgments:

Vincent Fatica provided useful suggestions for testing and performance.

#### Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

Primes is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

#### Download:

You can download the current version of the plugin from http://charlesdye.net/dl/primes.zip.