Method Lag

Lag<TSource>(IEnumerable<TSource>, int)

Produces a projection of a sequence by evaluating pairs of elements separated by a negative offset.

Declaration

public static IEnumerable<(TSource current, TSource? lag)> Lag<TSource>(this IEnumerable<TSource> source, int offset)

Parameters

Type	Name	Description
IEnumerable<TSource>	source	The sequence over which to evaluate lag
int	offset	The offset (expressed as a positive number) by which to lag each value of the sequence

Returns

Type	Description
IEnumerable<(TSource current, TSource lag)>	A sequence of tuples with the current and lagged elements

Type Parameters

Name	Description
TSource	The type of the elements of the source sequence

Remarks

For elements prior to the lag offset, default(TSource?) is used as the lagged value.

This operator evaluates in a deferred and streaming manner.

Examples

The following code example demonstrates how to get elements along with a previous value using Lag.

var sequence = new[] { "foo", "bar", "baz" };

// get lagged elements
var result = sequence.Lag(1);

Console.WriteLine(
    "[" +
    string.Join(", ", result) +
    "]");

// This code produces the following output:
// [(foo, ), (bar, foo), (baz, bar)]

Exceptions

Type	Condition
ArgumentNullException	source is null.
ArgumentOutOfRangeException	offset is below 1.

Lag<TSource, TResult>(IEnumerable<TSource>, int, Func<TSource, TSource?, TResult>)

Produces a projection of a sequence by evaluating pairs of elements separated by a negative offset.

Declaration

public static IEnumerable<TResult> Lag<TSource, TResult>(this IEnumerable<TSource> source, int offset, Func<TSource, TSource?, TResult> resultSelector)

Parameters

Type	Name	Description
IEnumerable<TSource>	source	The sequence over which to evaluate lag
int	offset	The offset (expressed as a positive number) by which to lag each value of the sequence
Func<TSource, TSource, TResult>	resultSelector	A projection function which accepts the current and lagged items (in that order) and returns a result

Returns

Type	Description
IEnumerable<TResult>	A sequence produced by projecting each element of the sequence with its lagged pairing

Type Parameters

Name	Description
TSource	The type of the elements of the source sequence
TResult	The type of the elements of the result sequence

Remarks

For elements prior to the lag offset, default(TSource?) is used as the lagged value.

This operator evaluates in a deferred and streaming manner.

Examples

The following code example demonstrates how to get elements along with a previous value using Lag.

var sequence = new[] { "foo", "bar", "baz" };

// get lagged elements
var result = sequence.Lag(1, (cur, lag) => new { cur, lag, });

Console.WriteLine(
    "[" +
    string.Join(", ", result) +
    "]");

// This code produces the following output:
// [{ cur = foo, lag =  }, { cur = bar, lag = foo }, { cur = baz, lag = bar }]

Exceptions

Type	Condition
ArgumentNullException	source or resultSelector is null.
ArgumentOutOfRangeException	offset is below 1.

Lag<TSource, TResult>(IEnumerable<TSource>, int, TSource, Func<TSource, TSource, TResult>)

Produces a projection of a sequence by evaluating pairs of elements separated by a negative offset.

Declaration

public static IEnumerable<TResult> Lag<TSource, TResult>(this IEnumerable<TSource> source, int offset, TSource defaultLagValue, Func<TSource, TSource, TResult> resultSelector)

Parameters

Type	Name	Description
IEnumerable<TSource>	source	The sequence over which to evaluate lag
int	offset	The offset (expressed as a positive number) by which to lag each value of the sequence
TSource	defaultLagValue	A default value supplied for the lagged value prior to the lag offset
Func<TSource, TSource, TResult>	resultSelector	A projection function which accepts the current and lagged items (in that order) and returns a result

Returns

Type	Description
IEnumerable<TResult>	A sequence produced by projecting each element of the sequence with its lagged pairing

Type Parameters

Name	Description
TSource	The type of the elements of the source sequence
TResult	The type of the elements of the result sequence

Remarks

For elements prior to the lag offset, defaultLagValue is used as the lagged value.

This operator evaluates in a deferred and streaming manner.

Examples

The following code example demonstrates how to get elements along with a previous value using Lag.

var sequence = new[] { "foo", "bar", "baz" };

// get lagged elements
var result = sequence.Lag(1, "LAG", (cur, lag) => new { cur, lag, });

Console.WriteLine(
    "[" +
    string.Join(", ", result) +
    "]");

// This code produces the following output:
// [{ cur = foo, lag = LAG }, { cur = bar, lag = foo }, { cur = baz, lag = bar }]

Exceptions

Type	Condition
ArgumentNullException	source or resultSelector is null.
ArgumentOutOfRangeException	offset is below 1.