TimestampLinkedList

Git Source

Title: TimestampLinkedList

A library for managing linked lists of uint48 timestamps in descending order

Each list maintains timestamps in descending chronological order (newest first)

Functions

add

Adds a new timestamp to the list in descending order

Does nothing if timestamp already exists

This function will revert if:

• The timestamp is 0

function add(List storage list, uint48 timestamp) internal;

Parameters

Name	Type	Description
list	List	The list to add to
timestamp	uint48	The timestamp to add

findLastBefore

Finds the largest timestamp that is less than or equal to the target

Returns 0 if no such timestamp exists

function findLastBefore(List storage list, uint48 target) internal view returns (uint48);

Parameters

Name	Type	Description
list	List	The list to search
target	uint48	The target timestamp

Returns

Name	Type	Description
<none>	uint48	The largest timestamp ≤ target, or 0 if none found

findFirstAfter

Finds the smallest timestamp that is greater than the target

Returns 0 if no such timestamp exists

function findFirstAfter(List storage list, uint48 target) internal view returns (uint48);

Parameters

Name	Type	Description
list	List	The list to search
target	uint48	The target timestamp

Returns

Name	Type	Description
<none>	uint48	The smallest timestamp > target, or 0 if none found

contains

Checks if a timestamp exists in the list

function contains(List storage list, uint48 timestamp) internal view returns (bool);

Parameters

Name	Type	Description
list	List	The list to check
timestamp	uint48	The timestamp to look for

Returns

Name	Type	Description
<none>	bool	True if timestamp exists in the list

getHead

Returns the most recent (head) timestamp

function getHead(List storage list) internal view returns (uint48);

Parameters

Name	Type	Description
list	List	The list to check

Returns

Name	Type	Description
<none>	uint48	The head timestamp, or 0 if list is empty

getPrevious

Returns the previous timestamp for a given timestamp

function getPrevious(List storage list, uint48 timestamp) internal view returns (uint48);

Parameters

Name	Type	Description
list	List	The list to check
timestamp	uint48	The timestamp to get the previous for

Returns

Name	Type	Description
<none>	uint48	The previous timestamp, or 0 if none

isEmpty

Checks if the list is empty

function isEmpty(List storage list) internal view returns (bool);

Parameters

Name	Type	Description
list	List	The list to check

Returns

Name	Type	Description
<none>	bool	True if the list is empty

length

Returns the number of elements in the list

This is an O(n) operation, use sparingly

function length(List storage list) internal view returns (uint256);

Parameters

Name	Type	Description
list	List	The list to count

Returns

Name	Type	Description
<none>	uint256	The number of timestamps in the list

toArray

Returns all timestamps in the list in descending order

This is an O(n) operation with O(n) memory allocation, use sparingly

function toArray(List storage list) internal view returns (uint48[] memory timestamps);

Parameters

Name	Type	Description
list	List	The list to convert to array

Returns

Name	Type	Description
timestamps	uint48[]	Array of timestamps in descending order

Errors

TimestampLinkedList_InvalidTimestamp

error TimestampLinkedList_InvalidTimestamp(uint48 timestamp);

Structs

List

Structure representing a timestamp linked list

struct List {
    uint48 head;
    mapping(uint48 => uint48) previous;
}

Properties

Name	Type	Description
head	uint48	The most recent (largest) timestamp in the list
previous	mapping(uint48 => uint48)	Mapping from timestamp to the previous (older) timestamp