35.4 Chain accessors and mutators

The following syntactic bindings are exported by the library (vicare containers chains). The bindings whose name is prefixed with $ are unsafe operations: they do not validate their arguments before accessing them.

Function: chain-link-next link

Function: $chain-link-next link

Accessor for the next link in the forwards direction. Return null or an instance of <chain-link>.

Function: chain-link-prev link

Function: $chain-link-prev link

Accessor for the next link in the backwards direction. Return null or an instance of <chain-link>.

Function: chain-link-next-set! link chain

Function: $chain-link-next-set! link chain

Set the next link of link in the forwards direction; chain can be null or an instance of <chain-link>. If chain is an instance of <chain-link>: chain is mutated to reference link as its previous link.

Function: chain-link-prev-set! link chain

Function: $chain-link-prev-set! link chain

Set the next link of link in the backwards direction; chain can be null or an instance of <chain-link>. If chain is an instance of <chain-link>: chain is mutated to reference link as its next link.

Function: chain-front chain

Function: $chain-front chain

Return the first link in the chain of which chain is a link; return the last link in the backwards direction. Return chain itself if chain is null or the first link. Circular chains are forbidden.

Function: chain-rear chain

Function: $chain-rear chain

Return the last link in the chain of which chain is a link; return the last link in the forwards direction. Return chain itself if chain is null or the last link. Circular chains are forbidden.

Function: chain-push-front! chain new-front-link

Function: $chain-push-front! chain new-front-link

Prepend a new chain link to the chain of which chain is a link; return new-front-link itself. If chain is null: do nothing and return new-front-link itself.

Function: chain-push-rear! chain new-rear-link

Function: $chain-push-rear! chain new-rear-link

Append a new chain link to the chain of which chain is a link; return new-rear-link itself. If chain is null: do nothing and return new-rear-link itself.

Function: chain-pop-front! chain

Function: $chain-pop-front! chain

Remove the first link in chain and return 2 values: the removed <chain-link> instance and the new first link in the chain. If chain is null: raise an assertion violation. If chain has only one link: return that link and null.

Function: chain-pop-rear! chain

Function: $chain-pop-rear! chain

Remove the last link in chain and return 2 values: the removed <chain-link> instance and the new first link in the chain. If chain is null: raise an assertion violation. If chain has only one link: return that link and null.

Function: chain-link-remove! link

Function: $chain-link-remove! link

Extract link from its chain and return it. The previous and next links, if any, are chained together.

(let* ((A (chain 0 1 2 3 4))
       (B (chain-link-next A))
       (C (chain-link-next B))
       (D (chain-link-next C))
       (E (chain-link-next D)))
  (chain-link-remove! C)
  (values (chain->list A)
          (chain->list C)
          (chain->list E)))
⇒ (0 1 3 4) (2) (0 1 3 4)

Function: chain-index-forwards! chain idx

Function: $chain-index-forwards! chain idx

Return the object referenced by the link in chain at index idx. idx must be a non–negative exact integer representing a zero–based index; the count starts from the link chain and proceeds in the forwards direction.

(define C
  (chain-link-next
     (chain-link-next
        (chain 10 11 12 13 14))))

(chain-index-forwards C 2)      ⇒ 14

Function: chain-index-backwards! chain idx

Function: $chain-index-backwards! chain idx

Return the object referenced by the link in chain at index idx. idx must be a non–negative exact integer representing a zero–based index; the count starts from the link chain and proceeds in the backwards direction.

(define C
  (chain-link-next
     (chain-link-next
        (chain 10 11 12 13 14))))

(chain-index-backwards C 2)     ⇒ 10