1 :Info: radix_indicator_string_:  2022-05-06  radix_indicator_string_
  2 
  3 Function: This subroutine checks a numeric string to determine whether
  4 it ends with a radix indicator.  If such indicator is appended to the
  5 string, it specifies a numeric base (or radix) used to express digits
  6 in the string.  See "List of radix indicators" for information about
  7 the formats of a radix indicator string.
  8 
  9 
 10 Syntax:
 11 declare radix_indicator_string_ entry (char(*), fixed bin, fixed bin,
 12    fixed bin, fixed bin, fixed bin(35));
 13 call radix_indicator_string_( number_string, default_base,
 14    number_length_without_radix, effective_base, radix_fail_index,
 15    code);
 16 
 17 
 18 Arguments:
 19 number_string
 20    is a numeric string which may end with a radix indicator.
 21    (Input)
 22 default_base
 23    is the base to be used if the input string does not have a trailing
 24    radix indicator.  This base may be any integer between 2 to 16
 25    inclusive. (Input)
 26 number_length_without_radix
 27    is the length of the portion of number_string with any trailing
 28    whitespace and any radix indicator removed.  The calling program
 29    must interpret these leading characters to complete conversion of
 30    number_string to an arithmetic data type. (Output)
 31 
 32 
 33 effective_base
 34    is either default_base, or the base specified by any radix
 35    indicator string appended to the number_string.  The calling
 36    program should interpret remaining characters of number_string
 37    using this numeric base. (Output)
 38 radix_fail_index
 39    index within number_string of the leftmost incorrect character
 40    of a radix indicator. (Output)
 41 code
 42    is one of the following status code if an error was found when
 43    examining the radix indicator. (Output)
 44     error_table_$bad_arg:         unsupported default_base value.
 45     error_table_$bad_conversion:  invalid radix indicator.
 46 
 47 
 48 List of radix indicators:
 49    Indicator characters may also be given in uppercase.
 50 b, _b
 51    the number is interpreted as a base two number (binary).
 52    See "Notes" below.
 53 q, _q
 54    the number is interpreted as a base four number (quaternary).
 55 o, _o
 56    the number is interpreted as a base eight number (octal).
 57 d, _d
 58    the number is interpreted as a base ten number (decimal).
 59    See "Notes" below.
 60 x, _x
 61    the number is interpreted as a base sixteen number (hexadecimal).
 62 
 63 
 64 rN, _rN
 65    the number is interpreted in the base N which is a decimal number
 66    between 2 and 16 inclusive.
 67 
 68 
 69 Notes:  The following subroutines are known to accept numbers which
 70 include optional radix indicators:
 71     cv_fixed_point_string_,
 72     cv_integer_string_, cv_integer_string_check_
 73     cv_binary_, cv_binary_check_
 74     cv_oct_, cv_oct_check_
 75     cv_dec_, cv_dec_check_
 76     cv_hex_, cv_hex_check_
 77 
 78 
 79 The following command/active functions are known to accept numbers
 80 which include optional radix indicators:
 81     binary, bin
 82     octal, oct
 83     decimal, dec
 84     hexadecimal, hex
 85 
 86     plus, minus, times, divide, quotient, mod, max, min, trunk, floor,
 87       ceil, round
 88     calc
 89 
 90 
 91 Use a radix indicator beginning with underscore (_) if the
 92 effective numeric base includes "b" and "d" as valid digits.
 93 
 94 For example, if the effective numeric base is 16, a hexadecimal string
 95 might end with a "d" digit (e.g., 10d) in which the final "d" is
 96 treated as a digit in the number.  To treat it as a radix indicator,
 97 use a radix indicator beginning with underscore (e.g., 10_d).
 98 
 99 
100 Examples:
101 The following number strings show uses of a radix indicator.  These
102 examples assume decimal as the default numeric base.
103 
104 Hexadecimal numbers:  100x              100.01x
105 Decimal numbers:      256   256d  256.  2.56E+2_d
106 Octal numbers:        400o  400.o       400.002o
107 Binary numbers:       100000000b        100000000.00000001b
108 
109 
110 :Info: radix_indicator.gi: radix_indicator:  2021-11-29  radix indicator
111 
112 An ASCII representation of a number may include a final radix
113 indicator string to specify the numeric base (or radix) of the digits
114 in the ASCII string.  Most programs assume a decimal base for numeric
115 string data.  A radix indicator appended to the string can override
116 that assumption.
117 
118 
119 List of radix indicators:
120    Indicator characters may also be given in uppercase.
121 b, _b
122    the number is interpreted as a base two number (binary).
123 q, _q
124    the number is interpreted as a base four number (quaternary).
125 o, _o
126    the number is interpreted as a base eight number (octal).
127 d, _d
128    the number is interpreted as a base ten number (decimal).
129 x, _x
130    the number is interpreted as a base sixteen number (hexadecimal).
131 
132 
133 rN, _rN
134    the number is interpreted in the base N which is a decimal number
135    between 2 and 16 inclusive.
136 
137 
138 Notes: Use a radix indicator beginning with underscore (_) if the
139 effective numeric base includes "b" and "d" as valid digits.
140 
141 For example, if the effective numeric base is 16, a hexadecimal string
142 might end with a "d" digit (e.g., 10d) in which the final "d" is
143 treated as a digit in the number.  To treat it as a radix indicator,
144 use a radix indicator beginning with underscore (e.g., 10_d).
145 
146 
147 Examples:
148 The following number strings show uses of a radix indicator.  These
149 examples assume decimal as the default numeric base.
150 
151 Hexadecimal numbers:  100x              100.01x
152 Decimal numbers:      256   256d  256.  2.56E+2_d
153 Octal number:         400o  400.o       400.002o
154 Binary number:        100000000b        100000000.00000001b
155 
156 
157 :hcom:
158 /****^  HISTORY COMMENTS:
159   1) change(2021-11-29,GDixon), approve(2022-07-13,MCR10101),
160      audit(2022-07-27,Swenson):
161      A) Initial description of new radix_indicator_string_ subroutine.
162      B) Added general info description of radix indicator strings.
163   2) change(2022-05-06,GDixon), approve(2022-07-13,MCR10101),
164      audit(2022-07-27,Swenson):
165      A) Add cv_fixed_point_string_ to list of subroutines that support
166         use of a radix indicator string.
167                                                    END HISTORY COMMENTS */