Array Scanning

Scanning refers to the operation that applies a binary function recursively as follows:

Let x be an input vector and f be a binary operator, then the output y is a vector of the same length given by

For example, the function cumsum is a special case of array scanning.

This package provides both generic scanning functions, such as scan, scan!, mapscan, and mapscan!, as well as specialized scanning functions, such as cumsum and cumsum!, etc.

Generic Scanning

Synopsis

Let op be a binary operator, f1, f2, and f3 be respectively unary, binary, and ternary functors.

scan(op, x)                 # scan x using operator op
mapscan(op, f1, x)          # scan f1(x)
mapscan(op, f2, x, y)       # scan f2(x, y)
mapscan(op, f3, x, y, z)    # scan f3(x, y, z)

scan!(r, op, x)             # write the results of scanning of x to r
mapscan!(r, op, f1, x)
mapscan!(r, op, f2, x, y)
mapscan!(r, op, f3, x, y, z)

scan!(op, x)                # inplace scanning of x using operator op

Both scan and scan! accepts a dimension argument for scanning vectors along a specific dimension.

scan(op, x, dim)                # scan vectors of x along dim using operator op
mapscan(op, f1, x, dim)         # scan vectors of f1(x) along dim
mapscan(op, f2, x, y, dim)      # scan vectors of f2(x, y) along dim
mapscan(op, f3, x, y, z, dim)   # scan vectors of f3(x, y, z) along dim

scan!(r, op, x, dim)            # write the results of scanning of x to r
mapscan!(r, op, f1, x, dim)
mapscan!(r, op, f2, x, y, dim)
mapscan!(r, op, f3, x, y, z, dim)

scan!(op, x, dim)               # inplace scanning of x along dim

Note: mapscan and mapscan! use efficient ways to scan the terms without creating a temporary array such as f1(x). Hence, mapscan(op, f1, x) is generally faster than scan(op, f(x)).

Examples

scan(Add(), x)          # equivalent to cumsum(x)
scan(Add(), x, 1)       # equivalent to cumsum(x, 1)
scan!(Add(), x)         # writing cumsum(x) inplace (i.e. back to x)

Common Scanning Functions

For some common scanning operations, we provide specific functions to simplify the use.

# cumsum uses Add() as scanning operator

cumsum(x)
cumsum!(r, x)
cumsum!(x)

cumsum(f1, x)
cumsum(f2, x, y)
cumsum(f3, x, y, z)

cumsum!(r, f1, x)
cumsum!(r, f2, x, y)
cumsum!(r, f3, x, y, z)

# cummax uses Max() as scanning operator

cummax(x)
cummax!(r, x)
cummax!(x)

cummax(f1, x)
cummax(f2, x, y)
cummax(f3, x, y, z)

cummax!(r, f1, x)
cummax!(r, f2, x, y)
cummax!(r, f3, x, y, z)

# cummin uses Min() as scanning operator

cummin(x)
cummin!(r, x)
cummin!(x)

cummin(f1, x)
cummin(f2, x, y)
cummin(f3, x, y, z)

cummin!(r, f1, x)
cummin!(r, f2, x, y)
cummin!(r, f3, x, y, z)