General Information
Tutorials
Reference Manuals
Libraries
Translation Tasks
Tools
Administration
|
|
Library Reference
#include "strmath.h"
char *stradd(char *a, char *b, int base);
char *strsub(char *a, char *b, int base);
char *strmult(char *a, char *b, int base);
char *strdivf(char *a, char *b, int base);
char *strdivi(char *a, char *b, int base);
char *strrem(char *a, char *b, int base);
char *strpow(char *a, char *b, int base);
char *strneg(char *a, int base);
char *strsqrt(char *a, int base);
char *strnorm(char *a, int oldbase, int newbase, char *symbols);
char *strnumb(char *a, int *flag, int base);
int strmath(int select, ...);
This package is made available by adding the following line to a
type-specs file:
$/Tech/strmath.specs
The strings accepted by this package are essentially those of most higher
level languages:
[+/-][d*][.][d*][e[+/-]d*]
Here [] indicate optional parts,
+/- indicates that a sign may be present,
d indicates digits in the chosen base,
* indicates repetition,
. is a period representing the separation between
the integer and fractional parts of the number, and
e stands for any one of the exponent symbols given in
the control string EXP_SYMBOL.
Strings generated by the package have the same formats.
The actual characters used to represent digits, signs,
fractional separators and exponent symbols are determined by
default or by settings established by the strmath operation.
In general (with the exception of strnumb) the operations
return a NULL pointer when an error is found in the input values
or occurs during computation (e.g., overflow).
When a null value is returned, the global errno is set to
indicate the type of error.
If multiple errors occur, only the first is reported.
When operations are cascaded, with the result of one being used as an
operand of another, there is no need to check each operation individually.
If an error occurs in an early operation, the resulting NULL pointer will
be an invalid input to the next operation, thus guaranteeing that it will
yield a NULL pointer.
The NULL pointer will therefore propagate, and appear as the final value.
Since only the first error is reported, the global errno will
not be changed when any of the subsequent invalid inputs are detected.
The error codes used are defined in <errno.h>:
EINVAL
- An error in the format of an input value made it invalid.
(The function
strnumb can be used to assist in diagnosing
these problems.)
EDOM
- The given value falls outside the domain of the operation
(e.g. it is too large, or negative when a positive value is required).
ERANGE
- The result of the computation cannot be adequately
represented (e.g., divide by zero, overflow).
The usual rules for the use of errno apply:
It is not explicitly cleared.
If desired, this must be done before calling the desired function.
It is set by these functions only if an error occurs.
Most of the operations exported by the strmath module return pointer
values.
These pointers address the result string, which occupies space in a static
array.
All operations use the same static array for their results.
Thus the pointer returned by an operation will be valid only until another
operation of the module completes.
It is therefore the responsibility of each client of the module to make a
copy of any result string whose value must be preserved beyond the
completion of the next strmath operation.
The dyadic operations
stradd,
strsub,
strmult,
strdivf (full divide, possibly yielding a fractional part),
strdivi (integer quotient),
strrem (integer remainder) and
strpow
perform the indicated operation on two string operands;
the monadic operations
strneg and
strsqrt
perform the indicated operation on one string operand.
In each case the operation is performed in the radix given by base,
and the result is delivered as a string or NULL.
The strnorm operation converts a from radix oldbase to
radix newbase, normalizing it in the process, and the result is
delivered as a string.
The format of that string depends on the symbols argument:
symbols=NULL
- Whole number and fraction parts separated by the defined fractional
separator unless the result can be expressed as an integral value,
exponent marker and exponent if the length would exceed
integer_size
digits.
symbols is an empty string
- Sequence of digits if the length does not exceed
integer_size
digits, otherwise NULL.
symbols is a non-empty string
- A fractional separator is guaranteed to appear in the result.
The first character of
symbols is taken as the exponent marker.
If there are additional character in the string then they will be taken as
the fractional separator, the minus sign, and the plus sign respectively.
(The normally defined for these purposes will be used if they do not appear
in symbols.)
If the intent of the operation is simply to perform radix conversion, use
symbols=NULL.
The resulting string will be in the normal format delivered by other
operations of this module.
Using an empty string for symbols guarantees that the result is in
integer form.
(If this is not possible, the result will be NULL.)
This guarantee is important when the number is being output in a position
where an integer is required.
Using a non-empty string for symbols guarantees that the result is
in floating-point format.
It also allows one to easily vary the characters used for the exponent
marker, fractional separator, and signs.
This is important when the number is being output where a real is
required.
The strnumb operation is intended for input of numbers,
particularly in cases where there may be a radix marker at the end
of the number string.
It scans the string a and interprets it as a value in the radix
given by base.
If an error is found, the appropriate error value is returned in the
variable flag.
Otherwise flag will be set to zero.
The operation returns a pointer to the last character scanned.
This character will be the character at which the error was detected if
flag is nonzero, otherwise it is the first character that does not
belong to the number.
Termination of the scan is controlled by the setting of
STRM_CHECK_DIGITS.
The strmath operation is used to vary some characteristic of the
module.
It is called with a selection symbol given in the following table, and
one additional argument which is the value of the characteristic being set.
It returns the value 1 if the requested setting succeeded.
Otherwise 0 is returned and no selected value has been changed.
The caller is responsible for ensuring that the contents of the
string arguments are disjoint sets as described below.
strmath(STRM_DIGITS,`string')
- Change the string defining the set of valid digits.
For example, "0123456789ABCDEF" is a string that defines a set of digits for
bases 2-16.
Output strings are built by indexing this string to obtain the
representation of each computed digit.
The matching of alphabetic characters in input strings depends upon the
setting of
STRM_IGNORE_CASE.
Unpredictable results will be obtained if any character is repeated.
The default value is the string consisting of the digits '0'-'9',
the upper case alphabetic characters,
the lower case alphabetic characters, and
the characters '%' and '$'.
This string provides 64 distinct characters, thus supporting any radix not
greater than 64.
strmath(STRM_EXP_SYMBOLS,`string')
- Change the string defining the set of characters to be accepted as
representations of the exponent symbol.
Any character in the string is acceptable in input strings;
in output strings the first member of the set is used.
Unpredictable results will be obtained if any character is repeated
or is used as a digit.
The default value of this string is "^".
strmath(STRM_SIGNS,`string')
- Change the string defining the set of characters to be accepted as
representations of negative and positive signs.
The first element of the string is the character representing a negation,
and the remainder are all taken as representations of a positive
value.
In output strings the first element is used to show negation,
and the second value to represent a positive sign (if one is requested).
Unpredictable results will be obtained if any character is repeated
or is used as an exponent symbol or digit.
The default value of this string is "-+".
strmath(STRM_SEPARATORS,`string')
- Change the string defining the set of characters to be accepted as
representations of the fractional separator.
Any are acceptable in input strings; in output strings the first element
of the set is used.
Unpredictable results will be obtained if any character is repeated
or is used as a sign, exponent symbol or digit.
The default value of this string is ".".
strmath(STRM_EXP_BASE,`integer')
- Define the radix assumed for the exponents of numbers.
If this value is zero, the exponent radix is taken to be the same as
the number radix, which is supplied on each call to the strmath functions.
Otherwise the specified value is used as the exponent radix,
independent of the number radix.
strmath(STRM_INTEGER_SIZE,`integer')
- Set the maximum number of digits that a representation of an integer may have.
This value, plus
STRM_ROUND_SIZE, may be no greater than
ARITH_SIZE.
Values with more than STRM_INTEGER_SIZE significant digits
will be represented as values with exponents, even if integral in value.
The default value is ARITH_SIZE-2.
strmath(STRM_ROUND_SIZE,`integer')
- Set the number of additional digits a value may have a value may have
if not represented as an integer.
This value, plus
STRM_INTEGER_SIZE,
may be no greater than ARITH_SIZE.
Values with more than STRM_INTEGER_SIZE+STRM_ROUND_SIZE
significant digits will be rounded on output to values with no
more than that STRM_INTEGER_SIZE+STRM_ROUND_SIZE digits.
The default value is 2.
strmath(STRM_ROUNDING,`mode')
- Select the rounding mode to be applied to output values.
The following modes are recognized:
STRM_EVEN_ROUND
- The output value is rounded to the nearest value
representable in the given number of digits.
If two values are equally near,
the one with an even last digit will be returned.
This the default setting.
STRM_ZERO_ROUND
- The output value is rounded to the value
representable in the given number of digits
that is closest to and no greater in magnitude.
STRM_UP_ROUND
- The output value is rounded to the value
representable in the given number of digits
that is closest to but no less.
STRM_DOWN_ROUND
- The output value is rounded to the value
representable in the given number of digits
that is closest to but no greater.
STRM_HAND_ROUND
- The output value is rounded to the nearest value
representable in the given number of digits.
If two values are equally near,
the one with the greater magnitude will be returned
(as is normally done when computing by hand).
strmath(STRM_DENORMALIZE,`Flag')
Select the treatment of values with exponent -1.
`Flag'=1 allows values with exponents that would normally be -1
to be represented with a 0-valued digit before the fractional separator
on output.
If `Flag'=0, then the initial digit of an output value will
always be nonzero.
The default setting is 1.
strmath(STRM_INEXACT,`Flag')
Select the treatment of inexact values.
(An inexact value is one that has lost digits in the course of computation,
or whose value was derived from an inexact value.)
`Flag'=1 indicates that input values containing a fractional separator
should be regarded as inexact, and that
a fractional separator and fractional part should be included on
output of any inexact value.
`Flag'=0 indicates that all input values should be regarded as exact,
and that no fractional separator should be included on output
if the fractional part of the value being output is zero.
The default setting is 1.
strmath(STRM_CHECK_DIGITS,`Flag')
Select the treatment of non-digit characters on input.
`Flag'=1 indicates that all characters of a string be checked on input
to ensure that they are valid digits and
are legitimate in the specified number radix.
If this is not so, an error is reported by the operation reading the number.
`Flag'=0 indicates that the scan should end with the first
character that is not legitimately part of the number,
and no error is to be reported signalled.
The default setting is 1.
strmath(STRM_IGNORE_CASE,`Flag')
Select the treatment of the case of letters representing digits on input.
`Flag'=1 indicates that the case of letters in input values,
and the case of letters in the STRM_DIGITS string,
is to be ignored when matching and defining
the value of elements of an input number.
`Flag'=0 indicates that case is significant.
The default setting is 1.
|
