Skip to content
REFERENCE

U.PRIOR_VALS

Summary

Returns the prior values seen by this instance of U.PRIOR_VALS, before any values last changed. The method will both record the change history and return a given snapshot in a single call, or can be used to return points in change history

Syntax

=U.PRIOR_VALS(data, [history_size], [depth_to_return], [prepend_timestamp], [key])

Parameters

Parameter Required Description
data Yes The range, topic or cache key whose prior values should be returned recorded and returned
[history_size] No The number of changes to retain. A max of 1,000,000 is enforced
[depth_to_return] No The depth into the retained history to return, or "as_of()" to return values as of specified time. An optional 2nd column value can indicate the page number to return for multi-page histories, or "metadata" to return the metadata from a history of reports
[prepend_timestamp] No If set to TRUE then the time of the returned change is prepended as the top row of the result. A 2nd column can be provided and set to TRUE to have the depth level also prepended. A 3rd column, if set to TRUE, will prepend as columns instead of rows
[key] No A name to be assigned to the history of changes so that it can be accessed from another range

Behavior

The documented public interface is supported by the current U Add-in source signature and the maintained Usage Examples workbook. Optional parameters are shown in square brackets in the syntax above; omit the brackets when entering a formula.

Return Value

Returns the function result or action status described by the formula and parameters above. The maintained sources do not define a narrower, stable return contract for this function.

Examples

=U.PRIOR_VALS(B116:B118)

=U.PRIOR_VALS(B116:B118,D123,D126,D129)

=U.PRIOR_VALS(B116:B118,D137,,,D140)

Notes

  • Formula examples are preserved from maintained workbook usage and normalized to the current U. prefix.
  • Complete formulas demonstrate working patterns; they do not imply that undocumented option values are supported.
  • Where maintained sources do not specify every accepted value, default, or error message, this page does not infer one.
  • For functions that perform actions, use a visible trigger or supported block/throttle parameter to avoid unintended repetition during recalculation.