Module:Utils/doc: Difference between revisions

(42 intermediate revisions by 6 users not shown)

Line 1:

{{Documentation|{{dochead|header=library}}

This module provides several mathematical functions which are likely to be used frequently on the Xenharmonic Wiki.

Namely, the functions in this module can be called from other modules by using <code>require('Module:Utils')</code> and calling the ~~<code>_</code>-prefixed~~ functions.

Namely, the functions in this module can be called from other modules by using <code>require("Module:Utils")</code> and calling the desired functions.

~~== Functions ==~~

For pairs of functions with names that differ by a single leading underscore (for example, <code>gcd</code> and <code>_gcd</code>), the function ''with'' an underscore is meant to be called by other modules, and the function ''without'' an underscore can be used with <code>#invoke</code>.

* <code>eval_num_arg(input, def_value)</code> checks if <code>input</code> is a ~~number; on error, use <code>def_value</code>. This function is designed to be used by other modules only; it cannot be called with <code><nowiki>{{#invoke:}}</nowiki></code>.~~

* <code>log(x, b)</code> ~~returns the logarithm base <code>b~~</code> ~~of <code>x</code>. Parameter~~ <code>b</code> ~~defaults to base 2 (octave~~) ~~if it is omitted.~~

* <code>round(x, ~~prec)</code> returns <code>x</code> rounded to a precision of <code>prec</code> significant figures. Parameter <code>prec</code> defaults to 6 if it is omitted.~~

* <code>is_prime(n)</code> returns <code>true</code> if the ~~given integer <code>n</code> is a prime number. This~~ function is ~~designed~~ to ~~be used by other modules only; it cannot~~ be called ~~with <code><nowiki>{{#invoke:}}</nowiki></code>.~~

* <code>prime_factorization(n)</code> returns the prime factorization of the given integer <code>n</code> using the exponential form (in wikitext).

* <code>prime_factorization_raw(n)</code> returns a table encoding the prime factorization of <code>n</code>. This function is designed to be used by other modules ~~only; it cannot be called with <code><nowiki>{{#invoke:}}</nowiki></code>.~~

* <code>signum(x)</code> returns 1 for positive numbers, -1 for negative ones, ~~0 for zero~~ and ~~non-integer inputs. This~~ function ~~is designed to~~ be used ~~by other modules only; it cannot be called~~ with <code>~~<nowiki>{{~~#invoke~~:}}</nowiki>~~</code>.

<~~includeonly~~><hr><~~small~~>~~Documentation transcluded from~~ [[/~~doc~~]]</~~small~~> [[~~Category~~:~~Lua modules~~]]</~~includeonly~~>

=== Functions ===

; <code>trim(s)</code>

: Removes leading and trailing whitespaces (but not interior ones) from a string.

; <code>_yesno(frame)</code>

: Wrapper function for [[Module: Yesno]], for use with templates. (Module: Yesno does not have a corresponding template.)

; <code>_clamp(value, min_value, max_value)</code>

: Returns <code>value</code> such that it is between <code>min_value</code> and <code>max_value</code>.

; <code>table_contains(tbl, value, compare_func)</code> *

: Checks whether table <code>tbl</code> contains <code>value</code> and returns <code>true</code> (if found) or <code>false</code> if not found. Passing <code>compare_func</code> is optional; By default, <code>value</code> is a numeric value or a string; to check for other values, such as ratios defined by [[Module: Rational]], a comparison function <code>compare_func</code> must be passed in.

; <code>index_of(array, value, compare_func)</code> *

: Returns the first index with the given <code>value</code> (or nil if not found). Passing <code>compare_func</code> is optional. By default, <code>value</code> is a numeric value or a string; to check for other values, such as ratios defined by [[Module:Rational]], a comparison function <code>compare_func</code> must be passed in.

; <code>value_provided(s)</code> *

: Checks whether <code>s</code> is a non-empty string.

; <code>eval_num_arg(input, def_value)</code> *

: Evaluates <code>input</code> as a number, fraction notation supported but not other expressions; uses <code>def_value</code> on error.

; <code>log(x, b)</code>

: Returns the logarithm base <code>b</code> of <code>x</code>. Parameter <code>b</code> defaults to base 2 (octave) if it is omitted.

; <code>log2(x)</code>

: Returns the base-2 logarithm of <code>x</code>.

; <code>gcd(a, b)</code>

: Returns the greatest common divisor of <code>a</code> and <code>b</code>.

; <code>round_dec(x, places)</code>

: Returns <code>x</code> rounded to a precision of <code>places</code> decimal places. Parameter <code>places</code> defaults to 0 if it is omitted.

; <code>round(x, prec)</code>

: Returns <code>x</code> rounded to a precision of <code>prec</code> significant figures. Parameter <code>prec</code> defaults to 6 if it is omitted.

; <code>is_prime(n)</code>*

: Returns <code>true</code> if the given integer <code>n</code> is a prime number.

; <code>prime_factorization(n)</code>

: Returns the prime factorization of the given integer <code>n</code> using the exponential form (in wikitext).

; <code>prime_factorization_raw(n)</code> *

: Returns a table encoding the prime factorization of <code>n</code>.

; <code>signum(x)</code> *

: Returns 1 for positive numbers, −1 for negative ones, and 0 for zero and non-integer inputs.

; <code>next_young_diagram(d)</code>

: Returns the next Young diagram of the same size; the first one is <code>[N]</code>, the last one is <code>[1, 1, …, 1]</code>. After the last one, <code>nil</code> is returned. The input table is modified.

<nowiki>*</nowiki> These functions are designed to be used by other modules only; they cannot be called with <code><nowiki>{{#invoke: }}</nowiki></code>.

}}

@@ Line 1: / Line 1: @@
+{{Documentation|{{dochead|header=library}}
 This module provides several mathematical functions which are likely to be used frequently on the Xenharmonic Wiki.
-Namely, the functions in this module can be called from other modules by using <code>require('Module:Utils')</code> and calling the <code>_</code>-prefixed functions.
+Namely, the functions in this module can be called from other modules by using <code>require("Module:Utils")</code> and calling the desired functions.
-== Functions ==
+For pairs of functions with names that differ by a single leading underscore (for example, <code>gcd</code> and <code>_gcd</code>), the function ''with'' an underscore is meant to be called by other modules, and the function ''without'' an underscore can be used with <code>#invoke</code>.
-* <code>eval_num_arg(input, def_value)</code> checks if <code>input</code> is a number; on error, use <code>def_value</code>. This function is designed to be used by other modules only; it cannot be called with <code><nowiki>{{#invoke:}}</nowiki></code>.
-* <code>log(x, b)</code> returns the logarithm base <code>b</code> of <code>x</code>. Parameter <code>b</code> defaults to base 2 (octave) if it is omitted.
-* <code>round(x, prec)</code> returns <code>x</code> rounded to a precision of <code>prec</code> significant figures. Parameter <code>prec</code> defaults to 6 if it is omitted.
-* <code>is_prime(n)</code> returns <code>true</code> if the given integer <code>n</code> is a prime number. This function is designed to be used by other modules only; it cannot be called with <code><nowiki>{{#invoke:}}</nowiki></code>.
-* <code>prime_factorization(n)</code> returns the prime factorization of the given integer <code>n</code> using the exponential form (in wikitext).
-* <code>prime_factorization_raw(n)</code> returns a table encoding the prime factorization of <code>n</code>. This function is designed to be used by other modules only; it cannot be called with <code><nowiki>{{#invoke:}}</nowiki></code>.
-* <code>signum(x)</code> returns 1 for positive numbers, -1 for negative ones, 0 for zero and non-integer inputs. This function is designed to be used by other modules only; it cannot be called with <code><nowiki>{{#invoke:}}</nowiki></code>.
-<includeonly><hr><small>Documentation transcluded from [[/doc]]</small> [[Category:Lua modules]]</includeonly>
+{{Module introspection}}
+=== Functions ===
+; <code>trim(s)</code>
+: Removes leading and trailing whitespaces (but not interior ones) from a string.
+; <code>_yesno(frame)</code>
+: Wrapper function for [[Module: Yesno]], for use with templates. (Module: Yesno does not have a corresponding template.)
+; <code>_clamp(value, min_value, max_value)</code>
+: Returns <code>value</code> such that it is between <code>min_value</code> and <code>max_value</code>.
+; <code>table_contains(tbl, value, compare_func)</code> *
+: Checks whether table <code>tbl</code> contains <code>value</code> and returns <code>true</code> (if found) or <code>false</code> if not found. Passing <code>compare_func</code> is optional; By default, <code>value</code> is a numeric value or a string; to check for other values, such as ratios defined by [[Module: Rational]], a comparison function <code>compare_func</code> must be passed in.
+; <code>index_of(array, value, compare_func)</code> *
+: Returns the first index with the given <code>value</code> (or nil if not found). Passing <code>compare_func</code> is optional. By default, <code>value</code> is a numeric value or a string; to check for other values, such as ratios defined by [[Module:Rational]], a comparison function <code>compare_func</code> must be passed in.
+; <code>value_provided(s)</code> *
+: Checks whether <code>s</code> is a non-empty string.
+; <code>eval_num_arg(input, def_value)</code> *
+: Evaluates <code>input</code> as a number, fraction notation supported but not other expressions; uses <code>def_value</code> on error.
+; <code>log(x, b)</code>
+: Returns the logarithm base <code>b</code> of <code>x</code>. Parameter <code>b</code> defaults to base 2 (octave) if it is omitted.
+; <code>log2(x)</code>
+: Returns the base-2 logarithm of <code>x</code>.
+; <code>gcd(a, b)</code>
+: Returns the greatest common divisor of <code>a</code> and <code>b</code>.
+; <code>round_dec(x, places)</code>
+: Returns <code>x</code> rounded to a precision of <code>places</code> decimal places. Parameter <code>places</code> defaults to 0 if it is omitted.
+; <code>round(x, prec)</code>
+: Returns <code>x</code> rounded to a precision of <code>prec</code> significant figures. Parameter <code>prec</code> defaults to 6 if it is omitted.
+; <code>is_prime(n)</code>*
+: Returns <code>true</code> if the given integer <code>n</code> is a prime number.
+; <code>prime_factorization(n)</code>
+: Returns the prime factorization of the given integer <code>n</code> using the exponential form (in wikitext).
+; <code>prime_factorization_raw(n)</code> *
+: Returns a table encoding the prime factorization of <code>n</code>.
+; <code>signum(x)</code> *
+: Returns 1 for positive numbers, −1 for negative ones, and 0 for zero and non-integer inputs.
+; <code>next_young_diagram(d)</code>
+: Returns the next Young diagram of the same size; the first one is <code>[N]</code>, the last one is <code>[1, 1, …, 1]</code>. After the last one, <code>nil</code> is returned. The input table is modified.
+<nowiki>*</nowiki> These functions are designed to be used by other modules only; they cannot be called with <code><nowiki>{{#invoke: }}</nowiki></code>.
+}}