position-in-ring

position-in-ring-forward Functions

Summary

Finds the first ring element that matches a supplied item and returns its index.

Package

hcl

Signatures

position-in-ring ring item index &key test => result

position-in-ring-forward ring item index &key test => result

Arguments

`ring`⇩	A ring object created by make-ring.
`item`⇩	A Lisp object.
`index`⇩	A non-negative integer.
`test`⇩	A function designator for a function of two arguments.

Values

result

A non-negative integer or nil.

Description

The function position-in-ring finds in the ring ring the first element that matches item and returns its index, or nil if there is no match. The search starts from index index and proceeds "backward" up to the length of the ring (its current number of elements). In other words, it tests all the elements that would be returned by ring-ref with indices index, index+1, ... , length-1. It does not wrap around, so elements between indices 0 and index are not tested.

The function position-in-ring-forward does the same except that it searches from index "forward" to the insertion point. In other words, it tests the elements that would be returned by ring-ref with indices index, index-1, ..., 0.

The comparison is done by calling test, with item as first argument and each element in the ring as the second argument. The default value of test is eql.

Notes

test is called with the ring locked.

Compatibility notes

In LispWorks 6.1 and earlier versions, these functions are called find-in-ring and find-in-ring-forward. They have been renamed to match the Common Lisp convention that a function returning an index is named position-*. The old names are retained for backwards compatibility, but are deprecated.