fall

Arguments

Returns

On success, t, otherwise one of the following error messages:

(error "textlog: Time adjustment must be one of 'forward', 'backward' or 'closest'")
(error "textlog: Group or log label does not exist")
(error "textlog: Too few arguments to fall: # < #")
(error "textlog: Invalid command: fall")

or, if none of the above errors apply, nil.

Description

This command determines how the Cascade TextLogger will associate different values logged within a given tolerance.

This command corresponds to the Cogent C API function LG_Fall.

See Also

tolerance

Example

In the following example, the tolerance was set to 30000 nanoseconds, so each point is logged individually:

                       L1  L2  L3
    15:43:0198 Levels: 45  *   * 
    15:43:0200 Levels: 63  *   * 
    15:43:0203 Levels: *   80  * 
    15:43:0205 Levels: *   *   89
    15:43:0208 Levels: 72  *   * 
    15:43:0215 Levels: 78  *   *

If the following commands had been sent first:

(tolerance 1 0)
(fall forward L2)
(fall backward L3)

the log would look like this:

                       L1  L2  L3
    15:43:0198 Levels: 45  *   * 
    15:43:0200 Levels: 63  *   89
    15:43:0208 Levels: 72  80  *
    15:43:0215 Levels: 78  *   *

because now the tolerance is so wide that points L2 and L3 get logged on the same line as L1. Even though the change to L2 occurs before the change to L3, it is logged with the L1 value 72 rather than 63, because the forward mode causes it to be logged with the next changed value within the tolerance. The same thing applies to L3, but backward.

In another example, if these commands had been sent first:

(tolerance 1 0)
(fall closest)

the log would look like this:

                       L1  L2  L3
    15:43:0198 Levels: 45  *   * 
    15:43:0200 Levels: 63  80  * 
    15:43:0208 Levels: 72  *   89
    15:43:0215 Levels: 78  *   *

because now all points, including L2 and L3 get associated with the closest point in time.