Standard Library
Back to library index.
Package std-array (in std.i) - building and manipulating arrays
Index of documented functions or symbols:
DOCUMENT accum_dimlist, dims, d
accumulate a dimension argument D onto a dimension list DIMS.
This can be used to emulate the dimension lists supplied to the
array function. For example:
func myfunc
local dims;
while (more_args()) accum_dimlist, dims, next_arg();
...
}
DOCUMENT allof(x)
anyof(x)
nallof(x)
noneof(x)
Respectively:
returns 1 if every element of the array x is non-zero, else 0.
returns 1 if at least one element of the array x is non-zero, else 0.
returns 1 if at least one element of the array x is zero, else 0.
returns 1 if every element of the array x is zero, else 0.
SEE: allof
DOCUMENT array(value, dimension_list)
or array(type, dimension_list)
returns an object of the same type as VALUE, consisting of copies
of VALUE, with the given DIMENSION_LIST appended to the dimensions
of VALUE. Hence, array(1.5, 3, 1) is the same as [[1.5, 1.5, 1.5]].
In the second form, the VALUE is taken as scalar zero of the TYPE.
Hence, array(short, 2, 3) is the same as [[0s,0s],[0s,0s],[0s,0s]].
A DIMENSION_LIST is a list of arguments, each of which may be
any of the following:
(1) A positive scalar integer expression,
(2) An index range with no step field (e.g.- 1:10), or
(3) A vector of integers [number of dims, length1, length2, ...]
(that is, the format returned by the dimsof function).
SEE ALSO: reshape, is_array, dimsof, numberof, grow, span, use_origins, _lst
DOCUMENT digitize(x, bins) returns an array of longs with dimsof(X), and values i such that BINS(i-1) <= X < BINS(i) if BINS is monotonically increasing, or BINS(i-1) > X >= BINS(i) if BINS is monotonically decreasing. Beyond the bounds of BINS, returns either i=1 or i=numberof(BINS)+1 as appropriate.
DOCUMENT grow, x, xnext1, xnext2, ...
or grow(x, xnext1, xnext2, ...)
or _(x, xnext1, xnext2, ...)
lengthens the array X by appending XNEXT1, XNEXT2, etc. to its
final dimension. If X is nil, X is first redefined to the first
non-nil XNEXT, and the remainder of the XNEXT list is processed
normally. Each XNEXT is considered to have the same number of
dimensions as X, by appending unit-length dimensions if necessary.
All but this final dimension of each XNEXT must be right-conformable
(that is, conformable in the sense of the right hand side of an
assignment statement) with all but the final dimension of X.
The result has a final dimension which is the sum of the final
dimension of X and all the final dimensions of the XNEXT. Nil
XNEXT are ignored. The value of the result is obtained by
concatenating all the XNEXT to X, after any required broadcasts.
If invoked as a function, grow returns the new value of X; in
this case, X may be an expression. X must be a simple variable
reference for the subroutine form of grow; otherwise there is
nowhere to return the result. The subroutine form is slightly
more efficient than the function form for the common usage:
x= grow(x, xnext1, xnext2) is the same as
grow, x, xnext1, xnext2 the preferred form
The _ function is a synonym for grow, for people who want this
operator to look like punctuation in their source code, on analogy
with the array building operator [a, b, c, ...].
The _cat function is sometimes more appropriate than grow.
Usage note:
Never do this:
while (more_data) grow, result, datum;
The time to complete this loop scales as the SQUARE of the number
of passes! Instead, do this:
for (i=1,result=array(things,n_init) ; more_data ; i++) {
if (i>numberof(result)) grow, result, result;
result(i) = datum;
}
result = result(1:i-1);
The time to complete this loop scales as n*log(n), because the
grow operation doubles the length of the result each time.
DOCUMENT list = histinv(hist) returns a list whose histogram is HIST, hist = histogram(list), that is, hist(1) 1's followed by hist(2) 2's, followed by hist(3) 3's, and so on. The total number of elements in the returned list is sum(hist). All values in HIST must be non-negative; if sum(hist)==0, histinv returns []. The input HIST array may have any number of dimensions; the result will always be either nil or a 1D array.
SEE ALSO: histogram
DOCUMENT histogram(list)
or histogram(list, weight)
returns an array hist which counts the number of occurrences of each
element of the input index LIST, which must consist of positive
integers (1-origin index values into the result array):
histogram(list)(i) = number of occurrences of i in LIST
A second argument WEIGHT must have the same shape as LIST; the result
will be the sum of WEIGHT:
histogram(list)(i) = sum of all WEIGHT(j) where LIST(j)==i
The result of the single argument call will be of type long; the
result of the two argument call will be of type double (WEIGHT is
promoted to that type). The input argument(s) may have any number
of dimensions; the result is always 1-D.
KEYWORD: top=max_list_value
By default, the length of the result is max(LIST). You may
specify that the result have a larger length by means of the TOP
keyword. (Elements beyond max(LIST) will be 0, of course.)
DOCUMENT indgen(n)
or indgen(start:stop)
or indgen(start:stop:step)
returns "index generator" list -- an array of longs running from
1 to N, inclusive. In the second and third forms, the index
values specified by the index range are returned.
DOCUMENT integ(y, x, xp)
or integ(y, x, xp, which)
See the interp function for an explanation of the meanings of the
arguments. The integ function returns ypi which is the integral
of the piecewise linear curve (X(i), Y(i)) (i=1, ..., numberof(X))
from X(1) to XP. The curve (X, Y) is regarded as constant outside
the bounds of X. Note that X must be monotonically increasing or
DOCUMENT interp(y, x, xp)
or interp(y, x, xp, which)
returns yp such that (XP, yp) lies on the piecewise linear curve
(X(i), Y(i)) (i=1, ..., numberof(X)). Points beyond X(1) are set
to Y(1); points beyond X(0) are set to Y(0). The array X must be
one dimensional, have numberof(X)>=2, and be either monotonically
increasing or monotonically decreasing. The array Y may have more
than one dimension, but dimension WHICH must be the same length as
X. WHICH defaults to 1, the first dimension of Y. WHICH may be
non-positive to count dimensions from the end of Y; a WHICH of 0
means the final dimension of Y. The result yp has dimsof(XP)
in place of the WHICH dimension of Y (if XP is scalar, the WHICH
dimension is not present). (The dimensions of the result are the
same as if an index list with dimsof(XP) were placed in slot
WHICH of Y.)
DOCUMENT max(x)
or max(x, y, z, ...)
returns the scalar maximum value of its array argument, or, if
more than one argument is supplied, returns an array of the
maximum value for each array element among the several arguments.
In the multi-argument case, the arguments must be conformable.
DOCUMENT median(x)
or median(x, which)
returns the median of the array X. The search for the median takes
place along the dimension of X specified by WHICH. WHICH defaults
to 1, meaning the first index of X. The median function returns an
array with one fewer dimension than its argument X (the WHICH
dimension of X is missing in the result), in exact analogy with
rank reducing index range functions. If dimsof(X)(WHICH) is
odd, the result will have the same data type as X; if even, the
result will be a float or a double, since the median is defined
as the arithmetic mean between the two central values in that
case.
SEE ALSO: sort
DOCUMENT merge(true_expr, false_expr, condition)
returns the values TRUE_EXPR or FALSE_EXPR where CONDITION is
non-zero or zero, respectively. The result has the data type of
TRUE_EXPR or FALSE_EXPR, promoted to the higher arithmetic type
if necessary. The result has the dimensions of CONDITION.
The number of elements in TRUE_EXPR must match the number of
non-zero elements of CONDITION, and the number of elements in
FALSE_EXPR must match the number of zero elements of CONDITION.
(TRUE_EXPR or FALSE_EXPR should be nil if there are no such
elements of CONDITION. Normally, TRUE_EXPR and FALSE_EXPR should
be 1-D arrays if they are not nil.)
This function is intended for vectorizing a function whose
domain is divided into two or more parts, as in:
func f
big= (x>=threshhold);
wb= where(big);
ws= where(!big);
if (is_array(wb)) {
xx= x(wb);
fb=
}
if (is_array(ws)) {
xx= x(ws);
fs=
}
return merge(fb, fs, big);
}
DOCUMENT merge2(true_expr, false_expr, condition) returns the values TRUE_EXPR or FALSE_EXPR where CONDITION is non-zero or zero, respectively. The result has the data type of TRUE_EXPR or FALSE_EXPR, promoted to the higher arithmetic type if necessary. Unlike the merge function, TRUE_EXPR and FALSE_EXPR must be conformable with each other, and with the CONDITION.
DOCUMENT y = mergef(x, f1, cond1, f2, cond2, ... felse)
Evaluate F1(X(where(COND1))), F2(X(where(COND2))),
and so on, until FELSE(X(where(!(COND1 | COND2 | ...))))
and merge all the results back into an array Y with the
same dimensions as X. Each of the CONDi must have the
same dimensions as X, and they must be mutally exclusive.
During the evaluation of Fi, all of the local variables of
the caller of mergei are available. The Fi are called in
order, skipping any for which no X is in the specified interval.
Each Fi must return a double value with the same dimensions as
its input.
Additional input and output variables can be constructed using
the mergel index list employed by mergei, and using the mergeg
function. For example, let w be an additional input to and z be
an additional output from the function:
func myfunc(x, w, &z) {
z = array(0.0, dimsof(x, w));
x += z;
w += z;
return mergef(x, _myfunc_lo, x<1.234, _myfunc_hi);
}
func _myfunc_lo(x) {
wp = w(mergel); // part of w for this function
z = mergeg(z, );
return ;
}
func _myfunc_hi(x) {
wp = w(mergel); // part of w for this function
z = mergeg(z, );
return ;
}
DOCUMENT z = mergeg(z, value)
or z = mergeg(z)
If secondary results are to be returned from a mergef, besides
its return value, the Fi may construct them using mergeg.
z = mergeg(z, value)
where z is a variable in the original caller of mergef,
and value is its value.
z = []; or z = ;
y = mergef(x, f1, cond, f2);
z = mergeg(z); // this can now be omitted, but does no harm
...
func f1(x) {
z = mergeg(z, exprz(x));
return expry(x);
}
func f2(x) {
z = mergeg(z, exprz(x));
return expry(x);
}