clip

clip(X,Y,Z)

X is a numeric or temporal scalar/vector/matrix/table, or a dictionary with numeric or temporal values.

Y is a numeric or temporal scalar/vector/matrix/table indicating the lower bound for the clipping range.

Z is a numeric or temporal scalar/vector/matrix/table indicating the upper bound for the clipping range.

Data Type Requirements:

• If X is INTEGRAL, Y and Z must be INTEGRAL.
• If X is FLOATING or DECIMAL, Y and Z can be INTEGRAL, FLOATING or DECIMAL.
• If X is TEMPORAL, Y and Z must be the same TEMPORAL type.

Data Form Requirements:

• If X is a scalar or dictionary, Y and Z must be scalars.
• If X is a vector, Y and Z can be scalars, or vectors of the same length as X.
• If X is a matrix, Y and Z can be scalars, or matrices of the same dimension as X.
• If X is a table, Y and Z can be scalars, or tables of the same dimension as X.

Clips X to specified range.

Return value: X' of the same data type and form as X.

The following rules determine how X is clipped (If X is a dictionary, "element" indicates the dictionary value):

• When Y and Z are scalars, the clipping range is [Y, Z]. Values outside this range are clipped to the nearest boundary.
  • NULL Y or Z indicates no limit on the lower or upper bound.
  • If Y is greater than Z, all elements in X'areZ.
• When Y and Z are vectors, matrices, or tables, each elementXi is clipped within the range [Yi, Zi]. Note: If any element in Y or Z is NULL, the corresponding element in X' is also NULL.
• When Y or Z is a scalar, and the other is a vector, matrix, or table, each element Xi is clipped within the range [Y,Zi] or [Yi,Z].
  • The scalar represents a fixed boundary for all elements in X, while vector/matrix/table specify the boundary limits for Xi in the corresponding position.
  • If the scalar is NULL, no limit is set on the boundary. If any element in the vector, matrix or table is NULL, the corresponding element in X' is also NULL.
  • If Y is greater than Z for a specific position, the corresponding element in X' is set to Z.

If X is a matrix or table, the aforementioned calculations will be performed on each column.

Example 1. When Y and Z are scalars.

Set upper bound to 5:

X = table(1..10 as val1, 10..1 as val2)
Y = NULL // NULL means no limit
Z = 5

clip(X,Y,Z)

Set all elements to 3 (with Y>Z):

X = 1..10
Y = 6
Z = 3
clip(X,Y,Z) 
// output:[3,3,3,3,3,3,3,3,3,3]

Set a range [3,5]:

X = dict(`a`b`c`d`e`f,[1,2,3,4,5,6])
Y = 3
Z = 5
clip(X,Y,Z)

/*
output:
a->3
b->3
c->3
d->4
e->5
f->5
*/

Example 2. When Y and Z are vectors

X = [1,2,3,4,5,6,7,8,9,10]
Y = [0,1,2,5,6,6,6,NULL,7,7]
Z = [3,4,5,6,7,8,NULL,5,5,9]
clip(X,Y,Z)
// output:[1,2,3,5,6,6,,,5,9]

Example 3. When Y or Z is a scalar, and the other is a vector, matrix, or table

Set a clipping range [4,Z[i,j]]:

X = 1..8$2:4
Y = 4
Z = [5,6,5,6,NULL,3,5,6]$2:4
clip(X,Y,Z)