consume

consume, process

def process consume(
    available: number;
    requested: number)  : number

consume returns for every line of a table the amount taken from the available quantity to fulfill part of the overall requested demand. The consumption is applied sequentially using scan, depleting the total request over successive lines.

• available: A number representing the quantity available on the current line.
• requested: A scalar or vector representing the total quantity requested for the entire group.

For instance, we have a request for 15 elements, and we have 3 available lots of 10 elements each which must be consumed in a specific order (e.g. because of expiration dates). What is the quantity of each lot that is consumed by the request?

We could express such a request in Envision as follows:

Lots.QtyConsumed = consume(Lots.QtyAvailable; qtyRequested) scan Lots.Order

With the amounts defined above, this would return 10 for the first lot, 5 for the second lot, and 0 for the last lot.

It is also possible to use a vector instead of a scalar in the function call:

Lots.QtyConsumed = consume(Lots.QtyAvailable; Items.QtyRequested) by id scan Lots.Order

Example

table Items[Id] = with
  [|as Id, as Stock|]
  [|"a", 10|]
  [|"b", 7|]

table Orders = with
  [|as OId, as Qty|]
  [|"a", 1|]
  [|"a", 1|]
  [|"a", 2|]
  [|"a", 1|]
  [|"b", 5|]
  [|"b", 10|]
  [|"b", 25|]

// Set up the relation between Orders and Items by mapping 
// Orders.OId to Orders.Id (which should match Items' primary key). 
// This ensures that when the consume function later uses 'by Id', 
// it correctly pairs each order with its corresponding stock.
expect Orders.Id = Orders.OId

// Calculate the served quantity per order: the consume function 
// deducts from Items.Stock based on Orders.Qty, grouping orders 
// by Id. The 'scan auto' option processes the orders sequentially, 
// allocating stock until each order’s request is fulfilled.
Orders.ServedFromStock = consume(Orders.Qty; Items.Stock) by Id scan auto

show table "Orders" with
  Orders.Id
  Orders.Qty
  Orders.ServedFromStock

This example will produce the following output:

Note: The consume function will not subtract the consumed quantities from Items.Stock, it will only return the consumed quantities. In the above example, the consumed values returned by the function will be stored in the new table column Orders.ServedFromStock. The consume function will not subtract the consumed quantities from Items.Stock; it only returns the consumed quantities. In the above example, the returned consumption values are stored in the new table column Orders.ServedFromStock.

See also

• assoc.quantity