Section documentation for STACK-Maxima /basen
A collection of functions meant for dealing with base-N numbers coming through the expanded syntax mode and being presented as inert functions.
Like stackunits, stackbasen "objects" need to be handled with tools.
Unlike stackunits, stackbasen "objects" can be nonsense from the start,
the expanded syntax does not restrict the student from inputting something
like 0b012345 where the digits are most definitely not binary digits. Thus
one should always decide when to validate the objects, you may do it in
input validation or you might do it later in grading.
A stackbasen object is an inert function with exactly three arguments:
- The first argument is the raw input form of the number in a given base and format.
- The second argument defines the format. Currently, there are two options
for format:
"C"for0b101010style binary,0xF00Fstyle hexadecimal and0777for octal. Note thatbandxare always lower case in the second char of those two formats, otherwise digits may be upper or lower case or even mixed. Hexadecimal digits are 0-9 and A-F."S"forAB2Z_36for freely chosen bases from 2-36. The digits aro from 0-9 and A-Z (or a-z, case does not matter). The base after_is always presented in base-10.
- The third option is the raw base-10 integer defining the base, even when it is already interpretable from the two previous arguments we carry it as a helpful easily accessible part of the object.
Note that there are overridable functions defining the presentation of these
formats. You do not need to replace the whole stackbasen texput logic. By
default format "C" is being rendered as \texttt and "S" with \textrm.
Also note that while it may seem like one could simply replace all the logic
defining the digits and the hard limit of 36, changing the logic at this level
is not enough. Student input will only turn to stackbasen objects if lexer
level rules and AST-filters agree on the acceptable digits. And one cannot
adjust those through author accessible means. It is however, possible to use
string inputs and suitable redefinition of certain functions to go further.
sbasen_char_to_digit(char)
A function to convert singular characters to numbers used in
the stackbasen syntax. Basically, '"0"' -> '0' and '"A"' -> '10'.
Lower and upper case ASCII letters are considered the same.
| Argument name | type | description |
|---|---|---|
| char | string | a single character string. |
| Return type | description |
|---|---|
| integer | the matching number in the range 0-35, or false for unknown |
sbasen_construct_default_case
The option sbasen_construct_default_case controls the case of the digits
A-Z (or 10-35) when creating new stackbasen objects in logic.
Note that this is separate from the option sbasen_output_force_case,
which controls the presentation of existing, possibly student sourced
values.
By default this is "upper" and the generation will use uppercase letters
when need be.
The value "lower" will naturally use lowercase instead.
sbasen_construct_from_base10(number,format,base)
Given a positive base-10 integer and a format and a base settings will
convert bases and produce a stackbasen object with those settings.
Note that for "C" format only bases 2,8, and 16 are available. For "S"
bases 2-36 are possible.
For digits 10-35 will use ASCII letters and the case will be defined by
the option sbasen_construct_default_case, by default uppercase letters
will be used.
| Argument name | type | description |
|---|---|---|
| number | positive integer | base-10 number to convert |
| format | char | the format, either "S" or "C" |
| base | positive integer | the base as a integer in the range [2,36] |
| Return type | description |
|---|---|
| stackbasen | the value in the desired base and format |
sbasen_convert_to_base10(expression)
A function to convert stackbasen objects back to normal base-10 numbers,
will find all stackbasen instances in the input and replaces them with
raw base-10 integers.
Does not verify validity of those stackbasen objects, so might generate
interesting results.
| Argument name | type | description |
|---|---|---|
| expression | expression | an expression that might have stackbasen-objects in it. |
| Return type | description |
|---|---|
| expression | the original expression with all stackbasen-objects converted to raw integers. |
sbasen_convert_to_digits(sbasen_number)
A function to convert stackbasen objects into a list of digits
presented as base-10 numbers. With most significant digit first.
See sbasen_convet_to_digits_lsd for a variant with least significant
digit first.
Does not verify validity of those stackbasen objects, so might generate
interesting results. If a digit does not fit the 0-9+A-Z range expect to
see false in the list.
| Argument name | type | description |
|---|---|---|
| sbasen_number | stackbasen | the stackbasen-object to turn to a digit list |
| Return type | description |
|---|---|
| list | the digits interpereted as base-10 integers, most significant digit first |
sbasen_convert_to_digits_lsd(sbasen_number)
A function to convert stackbasen objects into a list of digits
presented as base-10 numbers. With least significant digit first.
See sbasen_convet_to_digits for a variant with most significant
digit first.
Does not verify validity of those stackbasen objects, so might generate
interesting results. If a digit does not fit the 0-9+A-Z range expect to
see false in the list.
| Argument name | type | description |
|---|---|---|
| sbasen_number | stackbasen | the stackbasen-object to turn to a digit list |
| Return type | description |
|---|---|
| list | the digits interpereted as base-10 integers, least significant digit first |
sbasen_convert_to_suffix_notation(expression)
Converts all stackbasen objects present in an expression to the suffix
notation. This should help when checking for equality but won't help
if values include padding, if that is the case you may need to use
sbasen_trim_padding.
To avoid issues with different cases will recreate all stackbasen objects.
And remap the digits. For digits 10-35 will use ASCII letters and the case
will be defined by the option sbasen_construct_default_case, by default
uppercase letters will be used.
| Argument name | type | description |
|---|---|---|
| expression | expression | an expression that might have stackbasen-objects in it. |
| Return type | description |
|---|---|
| expression | the original expression with all stackbasen-objects converted to use "S"-format. |
sbasen_output_force_case
The option sbasen_output_force_case forces the presentation
of digits in stackbasen objects to be outputted in a particular case even
if originally received in the other.
By default this is "preserve" and the original inputted form will be used.
The values "upper" and "lower" will convert cases.
Note, affects validation display only if defined in the preamble.
sbasen_texput_C_binary(sbasen_number)
A function to convert singular C binary format stackbasen object to
a LaTeX string presentation. By default \texttt{0b101} is the output
format.
Feel free to override this function in the preamble, if the style does not match your needs.
| Argument name | type | description |
|---|---|---|
| sbasen_number | stackbasen | a single base-N object in the "C"-format. |
| Return type | description |
|---|---|
| string | the matching LaTeX presentation |
sbasen_texput_C_hex(sbasen_number)
A function to convert singular C hex format stackbasen object to
a LaTeX string presentation. By default \texttt{0xAbc1} is the output
format.
Feel free to override this function in the preamble, if the style does not match your needs.
This function respects the option sbasen_output_force_case.
| Argument name | type | description |
|---|---|---|
| sbasen_number | stackbasen | a single base-N object in the "C"-format. |
| Return type | description |
|---|---|
| string | the matching LaTeX presentation |
sbasen_texput_C_octal(sbasen_number)
A function to convert singular C octal format stackbasen object to
a LaTeX string presentation. By default \texttt{0755} is the output
format.
Feel free to override this function in the preamble, if the style does not match your needs.
| Argument name | type | description |
|---|---|---|
| sbasen_number | stackbasen | a single base-N object in the "C"-format. |
| Return type | description |
|---|---|
| string | the matching LaTeX presentation |
sbasen_texput_suffix(sbasen_number)
A function to convert singular suffix format stackbasen object to
a LaTeX string presentation. By default {\textrm{123}}_{10} is the output format.
Feel free to override this function in the preamble, if the style does not match your needs.
This function respects the option sbasen_output_force_case.
| Argument name | type | description |
|---|---|---|
| sbasen_number | stackbasen | a single base-N object in the "S"-format. |
| Return type | description |
|---|---|
| string | the matching LaTeX presentation |
sbasen_validate(expression)
Validates a stackbasen object, i.e., checks that the "digits" are suitable
for the base. Returns either true for valid or a CASText fragment
describing the issue.
Suitable for bespoke validator use.
Note this is for a singular value, use the tree checking version
(sbasen_validate_tree) if you expect expressions or multiple literals.
Will complain if the received expression is not a singular value, even if
just a prefix op is present.
| Argument name | type | description |
|---|---|---|
| expression | expression | an expression to validate |
| Return type | description |
|---|---|
| CASText/bool | true if valid otherwise a CASText fragment. |
sbasen_validate_tree(expression)
Validates stackbasen objects present in the expression, i.e., checks that
the "digits" are suitable for the base. Returns either true for valid or
a CASText fragment describing the issues.
Suitable for bespoke validator use.
Note that will not consider non existence of stackbasen objects an issue.
| Argument name | type | description |
|---|---|---|
| expression | expression | an expression to validate |
| Return type | description |
|---|---|
| CASText/bool | true if valid otherwise a CASText fragment. |
stackbasen(textform,format,base)
An object combining a textual presentation of a base-N number with details
necessary for working with that number. Note that some details are overly
defined and when there is a conflict the two latter parameters are
the authoritative ones, the base being the deciding one of those two.
If this object comes from the student, do not assume that the object is
valid. Basically, the digits in the textform might not be suitable for
the base and it is possible to give a base beyond the supported ones.
You may use the validation functions sbasen_validate and
sbasen_validate_tree to check if the textform matches the constraints
set by the format and base.
You may create these objects directly, but if you wish to create one from
a raw base-10 number you might want to use the sbasen_construct_from_base10
function. Also if you are focused on base-2 then sbasen_convert_to_binary
can be useful for converting from any base or from raw base-10 to base-2.
Conversion back to raw base-10 happens with sbasen_convert_to_base10.
| Argument name | type | description |
|---|---|---|
| textform | string | the textual presentation that may be valid for this base and format |
| format | char | the format that is to be used, basically "C" for C-style integer literals, or "S" for STACK suffix style |
| base | integer | the base as an base-10 integer in the range of 2-36 |
| Return type | description |
|---|---|
| stackbasen | returns itself, does not evaluate on its own |