1 :Info: index_set: ixs:  2021-10-15  index_set, ixs
  2 
  3 Syntax as a command:  ixs SET1 ... -set SETn  {-control_arg}
  4 
  5 
  6 Syntax as an active function:  [ixs SET1 ... -set SETn  {-control_arg}]
  7 
  8 
  9 Function:  returns one or more integers, separated from each other by
 10 spaces.  Output integers have fixed(35, 0) precision and may be
 11 expressed as decimal, octal, or hexadecimal character strings.
 12 Desired integers are selected by giving a SET specification.
 13 
 14 
 15 Arguments:
 16    If several sets are given without -set control arguments, each
 17    specification includes all three arguments below.  If only one set
 18    is specified, FIRST and INCREMENT are optional.
 19 FIRST
 20    a starting integer for the SET.   (default: 1)
 21 BOUND
 22    an ending integer BOUND for the SET.
 23 INCREMENT
 24    gives the increment between set elements.  Elements of the SET
 25    descend in value if a negative increment is given.
 26    If FIRST > BOUND, the INCREMENT is automatically negated if
 27    needed.  (default: 1)
 28 
 29 
 30    See "Examples" below for use of the various specification formats.
 31    See also: "Notes on set specification".
 32 
 33 
 34 Control arguments:
 35 -set BOUND
 36    gives a SET specification consisting of only a bound integer.
 37    Defaults are used for the first element of the SET, and for the
 38    increment between SET elements.
 39 -set FIRST BOUND
 40    gives a SET specification consisting of a first element and bound.
 41    The default is used for the increment between SET elements.
 42 -set FIRST BOUND INCREMENT
 43    gives a complete SET specification: first element, bound (last
 44    element), and increment between elements.
 45 
 46 
 47 -set -specification_control_args...
 48    starts a new set specification.  It may be omitted for the first
 49    set specification.  It is followed by one or more of the set
 50    specification control arguments in the next section.  These may
 51    appear in any order, but must include either -to BOUND or
 52    -for COUNT to specify the length of the set.
 53 
 54 
 55 Control arguments (set specification):
 56    The following control arguments may be used to specify elements
 57    desired in the SET.  Either -to or -for must be given for each SET
 58    to specify its length.
 59 -from FIRST, -fm FIRST
 60    gives the first element of a SET.  (default: FIRST=1)
 61 -by INCREMENT
 62    gives the increment between SET elements.  Elements of the SET
 63    descend in value if a negative increment is given.  If
 64    FIRST > BOUND and INCREMENT > 0, then INCREMENT is automatically
 65    negated.  (default: INCREMENT=1)
 66 
 67 
 68 -to BOUND
 69    gives the bound (ending integer) in the range spanned by the SET.
 70    If an increment is given, it should be positive.  If
 71    FIRST > BOUND, the INCREMENT will automatically be negated to
 72    generate descending integers.
 73 -for COUNT
 74    gives the count of elements desired in the set.  Specify a negative
 75    increment to produce a set of descending integers.  Both -to and
 76    -for may not appear in the same SET specification.
 77 
 78 
 79 Control arguments (output radix):
 80    One of the following control arguments may be given to specify
 81    radix (numeric base) used when creating the output integers.
 82    Non-decimal output integers have the appropriate radix indicator
 83    appended to the number.
 84 -octal, -oct
 85    output octal integer character strings.
 86 -decimal, -dec
 87    output decimal integer character strings. (default)
 88 -hexadecimal, -hex
 89    output hexadecimal integer character strings.
 90 -unspec
 91    output each fixed bin(35) element of the SET as an unsigned
 92    12-digit octal value: the bits from unspec(element).
 93 
 94 
 95 Notes on input integers:
 96 A radix indicator may be appended to any input integer to specify its
 97 numeric base.  Decimal is assumed if no radix indicator is given.
 98 
 99    INDICATOR   NUMERIC BASE              EXAMPLES
100     b or _b      base  2 or binary         1101b
101     q or _q      base  4 or quaternary     113q  (=23d)
102     o or _o      base  8 or octal          21o
103     d or _d      base 10 or decimal        17d or 17
104     x or _x      base 16 or hexadecimal    11x
105    rN or _rN     where N is base value
106                   between 2 and 16         44r5  (=24d)
107 
108 A negative value may be given using a leading minus (-) character:
109    -23
110 
111 
112 For octal input, a negative value may also be given using a 12-digit
113 octal format in which the left-most digit is 5, 6, or 7:
114    -1o is same as 777777777777o
115 
116 Digits for bases 11 through 16 may be entered using letters for digit
117 values beyond 9:
118    0 1 2 3 4 5 6 7 8 9 A B C D E F
119 with letters accepted in either uppercase or lowercase.
120 
121 For hexadecimal input, a negative value may also be given using a
122 9-digit hex format in which the left-most digit is: 8, 9, A, B, C, D,
123 E, or F:
124    -2x is same as FFFFFFFFEx
125 
126 
127 Notes on set specification:
128 The prior version of index_set accepted a simpler SET specification
129 consisting of 3 integers without control arguments:
130   F  gives the FIRST (or starting) element of the SET.
131   B  gives the BOUND (or final) element of the SET.
132   I  gives the INCREMENT between SET elements.
133 This simpler specification is accepted only if no control arguments
134 are used.
135 
136 If only one SET is requested, the specification can be given as 1, 2,
137 or 3 integers in the following order:
138     ORDER       MEANING
139       B        all integers in range from 1 through B
140    F  B        all integers in range from F through B
141    F  B  I     every Ith integer in range from F through B
142 
143 
144 If n SET specifications are given and control arguments are not used,
145 each specification must contain all three integers:
146    F1  B1  I1  ...  Fn  Bn  In
147 
148 
149 Examples:  Both integer-only SET specifications and specifications
150 using control arguments are shown below.
151 
152   ixs 7
153   1 2 3 4 5 6 7
154 
155   ixs 3 7
156   3 4 5 6 7
157 
158   ixs 7 3 2
159   7 5 3
160 
161   ixs -set 7 3 2
162   7 5 3
163 
164 
165   ixs -set -from 7 -to 3 -by 2
166   7 5 3
167 
168   ixs 3 -for 7
169   3 4 5 6 7 8 9
170 
171   ixs 337o -for 10
172   223 224 225 226 227 228 229 230 231 232
173 
174   ixs 337o -for 10 -octal
175   337o 340o 341o 342o 343o 344o 345o 346o 347o 350o
176 
177   ixs 337o 350o -oct
178   337o 340o 341o 342o 343o 344o 345o 346o 347o 350o
179 
180 
181 The following example shows three SETs defined in one command.
182   ixs 5   -set -to 2 -from 7   -set 1 -to -5 -by 2
183   1 2 3 4 5
184 
185   7 6 5 4 3 2
186 
187   1 -1 -3 -5
188 
189 
190 The following example shows -unspec output format.
191   ixs 337o 350o -unspec
192   000000000337 000000000340 000000000341 000000000342
193   000000000343 000000000344 000000000345 000000000346
194   000000000347 000000000350
195 
196 
197 :hcom:
198 
199 
200 
201 /****^  HISTORY COMMENTS:
202   1) change(2021-10-21,GDixon), approve(2021-11-09,MCR10099),
203      audit(2021-11-09,Swenson), install(2021-11-09,MR12.8-1009):
204      Revise info segment to reflect expanded SET specification syntax in
205      rewritten code.
206                                                    END HISTORY COMMENTS */
207 
208 
209