The b Context


The b context is native to A+. It is not to be loaded.

Sorted Arguments to the b-Context Functions

The definitions of the b context functions refer to sorted arrays, or to permutation vectors that will reorder arrays in sorted order. If the array is simple, i.e., of depth 0, then sorted order means that the items are in nondescending, lexicographic order, which is described in the definition of Grade up. A permutation vector that puts a simple array in sorted order is therefore one that rearranges the items into nondescending, lexicographic order.

Nested scalars and vectors of depth 1 can also be in sorted order. In the case of a scalar a, this means that >a is in sorted order, while for a one-element vector a, it means that 0a is in sorted order. A nested vector a with two or more elements is said to be in sorted order if it is ordered like a dictionary with the items of 0a corresponding to the first letter of words, the items of 1a corresponding to the second letter, and so on. That is, the items of 0a are in sorted order; if i is any simple integer vector in increasing order for which the items of i#0a are identical, then i#1a is in sorted order; and so on.

For example, if

     c3 5'blue blue green'
     n10 20 5
then c is sorted, n is not sorted, but the nested pair (c;n) is sorted.

Uniform Frames and Comparable Cells

Two simple arrays a and b are said to have comparable n-cells if their n-cells have the same shape, i.e.,
(-n)a equals (-n)b. If a has rank k then the items of a are (k-1)-cells. The array b is said to have cells comparable to the items of a if a and b have comparable (k-1) cells. For example, the right argument of the primitive function Find has cells comparable to the items of the left argument.

If a and b are nested scalars of depth 1 then they are said to have comparable n-cells if >a and >b have comparable n-cells, and analogously, b is said to have cells comparable to the items of a if this is true of >a and >b. If a and b are nested vectors of depth 1, then they are said to have comparable n-cells if for every valid scalar index i of both a and b, the simple arrays ia and ib have comparable n-cells, and analogously for b having cells comparable to the items of a. In particular, a and b do not have to be of the same length.

Suppose a and b are nested vectors and b has cells comparable to the items of a. Then for every valid scalar index i, if r is the rank of ia, then the (r-1)-cells of ib have the same shape as the items of ia. Note that r may vary with i. The complementary frame of b has shape (-r-1)b. If all the complementary frames for all i are equal, b is said to have uniform complementary frames. Similarly, if all the counts #ia are the same for all i, then a is said to have uniform counts.

For example, if

     c3 5'blue greengreen'
     n10 20 15
     d2 2 5'greenblue red  green'
     m2 25 10 25 15
then the nested pair (d;m) has cells comparable to the items of the nested pair (c;n) and uniform complementary frames (the 2-frames of d and m), while (c;n) has uniform counts.

Definitions of b-Context Functions

Binary End b.e{y;x}

   Arguments and Result
See Binary Iota, b.i{y;x}.
   Dependency
Comparison Tolerance.
   Definition
b.e differs from b.i in only one way: the elements of the result are last occurrences instead of first. That is, each element n in the result corresponds to a cell or cross section of x, and the value n is the largest index for which the nth item or cross section of y is identical to the corresponding cell or cross section of x. If there is no such item or cross section of y, then n is the number of items (#y) or cross sections (#0,y) of y.

Binary End, with Permutation b.pe{y;p;x}

   Arguments and Result
See Binary Iota, with Permutation, b.p{y;p;x}.
   Dependency
Comparison Tolerance.
   Definition
b.pe{y;p;x} is to b.e{y;x} as b.p{y;p;x} is to b.i{y;x}. See Binary End; Binary Iota, with Permutation; and Binary Iota.

Binary Greater than or Equal to b.ge{y;x}

   Arguments and Result
See Binary Iota, b.i{y;x}.
   Dependency
Comparison Tolerance.
   Definition
The definition of b.i{y;x} is based on comparing whether or not subarrays or cross sections of x and y are identical, depending on whether x and y are simple or nested arrays. The definition of b.ge{y;x} is exactly the same, except that the comparison function is not "identical to", but "greater than or equal to". That is, in comparing two simple subarrays b and a of y and x, respectively, a is said to be greater than or equal to b if a does not come before b in lexicographic order. In the case where a and b are cross sections of the nested arrays x and y, respectively, a is said to be greater than or equal to b if for every valid scalar index j, the simple array j,a is greater than or equal to the simple array j,b (the ravels of a and b are used to include the case where they are scalars).

Note that when x and y are simple, the definition of b.ge{y;x} is identical to the definition of the primitive Bins function, yx, except that for b.ge, comparison tolerance is used when x and y are floating-point arrays.

Binary Greater than or Equal to, with Permutation b.pge{y;p;x}

   Arguments and Result
See Binary Iota, with Permutation, b.p{y;p;x}.
   Dependency
Comparison Tolerance.
   Definition
b.pge{y;p;x} is to b.ge{y;x} as b.p{y;p;x} is to b.i{y;x}. See Binary Greater than or Equal to; Binary Iota, with Permutation; and Binary Iota.

Binary Iota b.i{y;x}

   Arguments and Result
Both arguments x and y must be of the same type, one of character, integer, floating point, and boxed. The result is an integer array. If both are nested, then they must be scalars or vectors of depth 1.

In addition, x must have cells comparable to the items of y. If x and y are nested then x must have uniform complementary frames, y must be of uniform count (see "Uniform Frames and Comparable Cells"), and y must be sorted (see "Sorted Arguments to the b-Context Functions"). The shape of the result is the common value of the shapes of the complementary frames of x.

   Dependency
Comparison Tolerance.
   Definition
When x and y are simple arrays, the definition of b.i{y;x} is identical to the definition of Find, yx, except that in the case of b.i, the items of the left argument y must be in nondescending lexicographic order.

When y is a nested array, its contents are best viewed as fields in a database. Let j be any valid index of both ,x and ,y. From the database viewpoint, the disclosed element j,y is a field and its items (j,y)[k] are records in that field. Cross sections of records k#,y can be formed for scalar indices k. Since all fields j,y have the same number of items, every record is in some cross section.

According to the requirements on nested x and y, the cells in j,x of rank 0(j,y)-1 can also be viewed as records in the field j,y. The corresponding frames for all j,x have the same shape, and so cross sections of records (<l)#,x can also be formed for x.

For every cross section (<l)#,x there is a corresponding element n of the result, which is the smallest index for which that cross section is identical to the cross section (#x)n#,y. If there is no such index, then n is the number of cross sections in y, i.e., 0,y.

   Example
     c3 5'blue greengreen'
     n15 10 20
     y(c;n)
     d2 2 5'greenblue red  green'
     m2 25 10 25 15
     x(d;m)
     b.i{c;d}
 1 0
 3 1
     b.i{n;m}
 3 3
 2 1
In the last evaluation the left argument n is not sorted, and the result is not what we expect. The permutation 1 0 2 will put n in sort order. We can evaluate b.i{1 0 2#n;m}, or equivalently b.p{n;1 0 2;m}:
     b.p{n;1 0 2;m}
 3 1
 2 0
Even though n is not sorted, (c;n) is:
     b.i{y;x}
 3 0
 3 1

Binary Iota, with Permutation b.p{y;p;x}

   Arguments and Result
The arguments y and x, and the result, are as described for Binary Iota, b.i. The argument p is a vector of nonnegative, nonrepeating integers.
   Dependency
Comparison Tolerance.
   Definition
The purpose of this function is to provide the advantages of b.i in the cases when a potential left argument to b.i is too large to reorder into nondescending order, as is the case with many mapped files.

If x and y are simple arrays, then the argument p is a vector of indices of the items of y such that the elements of p#y are in nondecreasing, lexicographic order. The number of elements in p is not necessarily equal to the number of items of y. The expression b.p{y;p;x} is formally equivalent to b.i{p#y;x}, but the permuted array p#y is never actually formed.

If x and y are nested arrays then for every valid index j of ,x and ,y, the argument w is a vector of indices of the items of j,y such that the elements of w#j,y are in nondecreasing, lexicographic order. b.p{y;p;x;} is formally equivalent to b.i{z;x}, where

     zy
     z[#x](<p)#z[#x]
but z is never actually formed.

Binary Less than or Equal to b.le{y;x}

   Arguments and Result
See Binary Iota, b.i{y;x}.
   Dependency
Comparison Tolerance.
   Definition
b.le differs from b.ge in only two ways: the comparisons are made with "less than or equal to" instead of "greater than or equal to", and the elements of the result are last occurrences instead of first.

That is, in comparing two simple subarrays b and a of y and x, respectively, a is said to be less than or equal to b if a does not come after b in lexicographic order. In the case where a and b are cross sections of the nested arrays x and y, respectively, a is said to be less than or equal to b if for each valid index j, the simple array j,a is less than or equal to the simple array j,b (the ravels of a and b are used to include the case where they are scalars).

Secondly, each element n in the result is the largest index for which the nth item or cross section of y is less than or equal to the corresponding cell or cross section of x. If there is no such item or cross section of y, then n is the number of items (i.e., #y) or cross sections of y.

Binary Less than or Equal to, with Permutation b.ple{y;p;x}

   Arguments and Result
See Binary Iota, with Permutation, b.p{y;p;x}.
   Dependency
Comparison Tolerance.
   Definition
b.ple{y;p;x} is to b.p{y;p;x} as b.le{y;x} is to b.i{y;x}. See Binary Iota, with Permutation; Binary Less than or Equal to; and Binary Iota.

Binary Range b.r{y;x}

   Arguments and Result
See Binary Iota, b.i{y;x}. The result is an integer array whose shape is 2,b.i{y;x}.
   Dependency
Comparison Tolerance.
   Definition
0#b.r{y;x} is identical to b.i{y;x}, and the elements of 1#b.r{y;x} are the number of occurrences of the cells or cross sections of x in y.

Binary Range, with Permutation b.pr{y;p;x}

   Arguments and Result
See Binary Iota, with Permutation, b.p{y;p;x}. The result is an integer array whose shape is 2,b.p{y;x}.
   Dependency
Comparison Tolerance.
   Definition
b.pr{y;p;x} is to b.p{y;p;x} as b.r{y;x} is to b.i{y;x}. See Binary Iota, with Permutation; Binary Range; and Binary Iota.

Binary Unique b.u{y;x}

   Arguments and Result
The arguments are simple and the items of y are assumed to be unique. Otherwise, the arguments and result follow the rules for b.i{y;x} in the simple case.
   Dependency
Comparison Tolerance.
   Definition
The result is identical to Binary Iota, b.i{y;x}. Since, however, unique items in y are assumed, the algorithm is slightly faster. The use of this function is discouraged, as it may be removed.


doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.