movingProductBy()

Calculate the moving product of BigDecimal objects mapped from a Stream<INPUT> via a mappingFunction and looking back windowSize number of elements.

Implementation Notes

This implementation is suitable mapping an arbitrary Stream<INPUT> to BigDecimal via a mappingFunction; for a version that operates directly on a Stream<BigDecimal>, see movingProduct(). By default, nulls are ignored and play no part in calculations, see treatNullAs() and treatNullAsOne() below for ways to change this behavior. The default MathContext for all calculations is MathContext.DECIMAL64, but this can be overridden (see withMathContext(), below).

Signatures

movingProductBy(int windowSize, Function<INPUT, BigDecimal> mappingFunction)

windowSize - How many trailing elements to calculate the product from at any given point in the stream
mappingFunction - A non-null function to map stream INPUT elements into BigDecimal for calculation

Additional Methods

Method	Purpose
`includePartialValues()`	When calculating the moving product and the full size of the window has not yet been reached, the gatherer should emit values for what it has. See example.
`treatNullAsOne()`	When encountering a `null` value in a stream, treat it as `BigDecimal.ONE` instead. See example.
`treatNullAs(BigDecimal replacement)`	When encountering a `null` value in a stream, treat it as the given `replacement` value instead. See example.
`withMathContext(MathContext mathContext)`	Replace the `MathContext` used for all mathematical operations performed by this gatherer. See example.
`withOriginal()`	Include the original input value from the stream in addition to the calculated value in a `WithOriginal`record. See example.

Note: treatNullAsZero() is also a valid method on this gatherer, but it only makes sense in a very narrow set of circumstances.

Examples

Moving product of window size 3, mapped from an object

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  new BigDecimal("1.0")),
        new NamedValue("second", new BigDecimal("2.0")),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j.movingProductBy(3, NamedValue::value))
    .toList();

// [ 
//   BigDecimal("20.000"), 
//   BigDecimal("400.000"),
//   BigDecimal("6000.000") 
// ]

Including partial values

Showing that an in-process product is emitted for each element, even if there aren’t 3 elements from which to calculate a product yet.

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  new BigDecimal("1.0")),
        new NamedValue("second", new BigDecimal("2.0")),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j.movingProductBy(3, NamedValue::value).includePartialValues())
    .toList();

// [ 
//   BigDecimal("1.0"), 
//   BigDecimal("2.00"),
//   BigDecimal("20.000"), 
//   BigDecimal("400.000"),
//   BigDecimal("6000.000") 
// ]

Showing nulls are ignored by default

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  null),
        new NamedValue("second", null),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j.movingProductBy(3, NamedValue::value))
    .toList();

// [
//   BigDecimal("6000.000") 
// ]

Treating null as one

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  null),
        new NamedValue("second", null),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j.movingProductBy(3, NamedValue::value).treatNullAsOne())
    .toList();

// [
//   BigDecimal("10.0"), 
//   BigDecimal("200.00"), 
//   BigDecimal("6000.000") 
// ]

Replacing null with another `BigDecimal`

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  null),
        new NamedValue("second", null),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j.movingProductBy(3, NamedValue::value).treatNullAs(BigDecimal.TWO))
    .toList();

// [
//   BigDecimal("40.0"), 
//   BigDecimal("400.00"), 
//   BigDecimal("6000.00") 
// ]

Specifying a new `MathContext`

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  new BigDecimal("1.0")),
        new NamedValue("second", new BigDecimal("2.0")),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j
        .movingProductBy(3, NamedValue::value)
        .withMathContext(new MathContext(3, RoundingMode.DOWN))
    )
    .toList();

// [ 
//   BigDecimal("20.0"), 
//   BigDecimal("400"),
//   BigDecimal("600E+3") 
// ]

Emitting a record containing the original and calculated values

record NamedValue(String name, BigDecimal value) {}

Stream
    .of(
        new NamedValue("first",  new BigDecimal("1.0")),
        new NamedValue("second", new BigDecimal("2.0")),
        new NamedValue("third",  new BigDecimal("10.0")),
        new NamedValue("fourth", new BigDecimal("20.0")),
        new NamedValue("fifth",  new BigDecimal("30.0"))
    )
    .gather(Gatherers4j.movingProductBy(3, NamedValue::value).withOriginal())
    .toList();

// [ 
//   WithOriginal[original=NamedValue[name=third, value=10.0], calculated=20.000]
//   WithOriginal[original=NamedValue[name=fourth, value=20.0], calculated=400.000]
//   WithOriginal[original=NamedValue[name=fifth, value=30.0], calculated=6000.000]
// ]