[stdlib_math] Add function diff

[zoziha]

• Add diff: Differences and approximate derivatives

Description

Computes differences between adjacent elements of an array.

Note: Only diff for rank-1/rank-2 arrays at this stage. (If there is a higher rank demand in the future, we can consider extending it.)

API:
For a rank-1 array

y = [[stdlib_math(module):diff(interface)]](x [, n=1, prepend=<no value>, append=<no value>])

and for a rank-2 array

y = [[stdlib_math(module):diff(interface)]](x [, n=1, dim=1, prepend=<no value>, append=<no value>])

• X: real/integer types.
• n: Difference order.
• ...

Note

Originally diff should be putted in stdlib_linalg, but considering that diff can support date drived types in the future, now it is putted in stdlib_math.

Prior Art

• keurfonluu/forlab (Fortran)
• diff in Matlab
• diff in numpy

[gareth-nx]

I don't know whether this interface has been discussed anywhere so far? A few potential issues that come to mind are:

• This routine allocates its output on every call. I can imagine in some situations that could be inefficient. Users might wish to make a more efficient diff call by providing the output data. For that case a subroutine interface may be preferable.
• When computing differences in practice, there are different approaches that may be desired to treat the end-points. The current routines reduce the size of the array. But one might also wish to preserve the array size and do some kind of extrapolation at the missing entry. There can be a number of cases here (e.g. forward differences, backward differences, centred differences, with different implications for end-points).

Currently the routine won't support such things. While that might prove to be fine, I'd like to see some discussion to ensure we've chosen the right interface.

[jvdp1]

What is the state-of-the-art of such a function (e.g., how is it designed in other languages?)?

[jvdp1]

Thank you for this PR. Here are some suggestions and comments.

[jvdp1]

thank you. Here are a couple of minor comments.

[zoziha]

• #! is the comment header of fypp, which now is replaced by !.
• size(work, ..) -> size_work scalar. (see [stdlib_math] Add function diff #605 (comment))

[jvdp1]

LGTM. Pending a few comments, it could be merged IMO, Thank you @zoziha for this PR.

[zoziha]

Thank you @jvdp1 for your patient review, I have made changes accordingly :)

[jvdp1]

Thank you @zoziha. This PR is fine for me. If @gareth-nx or @awvwgk could have a final look, it would be nice ;)

[milancurcic]

Looks good, thank you! I left several suggestions in the spec doc.

[zoziha]

Thanks @milancurcic , I have made changes accordingly.
Since my English expressions may not be accurate, please point them out in time, thanks a lot.

[milancurcic]

@gareth-nx @awvwgk are you OK with this PR going forward?

[awvwgk]

Looks good to me.