A signal modeled as segments. Presumably the segments are linear, but since you pass your own Interpolate, nothing in this module enforces that, though there are some transformations that are only valid for linear segments.

A signal has no value before its first sample, and maintains a constant value of the last sample forever. There is an implicit discontinuity to the first sample, so if x is the first sample, then [(x, y), ..] is implicitly [(x, Nothing), (x, y), ...]. NumSignal uses 0 for not set, so unless the first y is also 0 it becomes [(x, 0), (x, y), ..].

This comes with a built-in X offset, so translation is cheap, via shift.

Each X should be >= the previous X, and there shouldn't be more than two equal Xs in a row. The first ensures that binary search works, and the second insures that I don't try to interpolate a zero length segment. Construction via from_samples should establish them, and transformations should maintain them.

However, a few functions in here can break them, e.g. map_x and invert, and I think trying to fix them would be expensive. So be careful with those. Functions should be robust against zero length segments, but if you break ordering you're out of luck.

If the y value doesn't have an Eq instance, there's no way to filter out redundant segments like [(0, 1), (1, 1), (2, 1)]. Functions specialized to NumSignal may make some effort to do that, but only if it seems worth it.

constant_val for NumSignals can be more clever, because it can compare Ys. Also NumSignals are implicitly 0 before the first sample.

Use this as the stand-in for "since the beginning of time."

The final sample extends for "all time". However, there's no value before the first sample. The reason is that I'd have to have a zero value for y, and there isn't really an appropriate one for pitch.

TODO I could simplify straight lines, but then I'd need Eq on y. Maybe do that separately for NumSignal.

Simplify away redundant samples.

Get a Ptr to the vector. This is Vector.Storable.unsafeWith.

The arguments may seem backwards, but I've always done it this way, and it seems to be more convenient in practice.

Like at, but if the x matches a discontinuity, take the value before instead of after.

Concatenate signals, where signals to the right replace the ones to the left where they overlap.

With concat, each signal start clips the signal to its left. This is the other way around, the final sample in the first signal is taken as its end, and it replaces the start of the second signal.

Drop the segments after the given time. The last segment may overlap it.

This is like drop_after, but meant to clip the signal directly on x, rather than at the first sample >=x. This means I might have to insert a new sample, which means copying the signal. This is intended to be a "drop at and after", but since signals extend infinitely to the right, I can only go up to x. TODO maybe signals should go to Nothing >= the last sample?

If the signal has only a point exactly at x, then return the empty signal. This is because the first sample is effectively a transition from Nothing, or 0.

Drop the segments before the given time. The first segment will start at or before the given time.

Like drop_before, but ensure that the signal starts exactly at the given time by splitting a segment that crosses it.

Shift the signal in time.

Map Ys. This resamples the signal, so it's valid for a nonlinear function.

Map Ys. Only valid if the function is linear.

Map Xs. The slopes will definitely change unless the function is adding a constant, but presumably that's what you want.

TODO this can break Signal invariants.

Drop a x1==x2 discontinuity at the given time, if there is one. Used for Block.trim_controls, which is a terrible hack that I'm trying to get rid of.

Swap X and Y. Y must be non-decreasing or this will break Signal invariants.

Integrate the signal.

Since the output will have more samples than the input, this needs a sampling rate. The sampling rate determines the resolution of the tempo track. So it can probably be fairly low resolution before having a noticeable impact.

Combine two vectors with the given function. The signals are resampled to have coincident samples, assuming linear interpolation. This only works for linear functions, so the result can also be represented with linear segments.

This is the same as resample, only for ys without a zero.

The output has the union of the Xs in the inputs, except where they match exactly. Discontinuities should get two Xs. This is the list version of sample_xs2.