find-instances | | unit-classes-specifier
space-instances
pattern
&key
filter-before
filter-after
use-marking
verbose
=> unit-instances | [Function]
|
Purpose
Retrieve unit instances from
space instances based on a retrieval pattern.
Package :gbbopen
Module :gbbopen-core
Arguments and values
Returns
A newly consed list of unit instances specified by
unit-class-specifier that reside on
space-instances and satisfy the specified pattern
and any predicate filters.
Detailed syntax
unit-classes-specifier ::= | t |
single-unit-class-specifier
| ( single-unit-class-specifier+) |
|
single-unit-class-specifier ::=
| atomic-unit-class |
( atomic-unit-class subclassing-specifier) |
|
atomic-unit-class ::= | unit-class |
unit-class-name |
|
subclassing-specifier ::=
| :plus-subclasses | :no-subclasses |
+ | = |
|
The shorthand +
subclasses specifier is equivalent to
:plus-subclasses
and =
to :no-subclasses
.
pattern ::=
| subpattern | t | :all |
|
subpattern ::=
| pattern-element | |
| (not subpattern) | |
| (and subpattern*) | |
| (or subpattern*) |
|
pattern-element ::= | ( pattern-op dimension-names
pattern-values option*) | |
| ( boolean-dimension-unary-pattern-op dimension-names
option*) |
|
pattern-op ::= | ordered-dimension-pattern-op | |
| enumerated-dimension-pattern-op | |
| boolean-dimension-binary-pattern-op |
|
ordered-dimension-pattern-op ::=
| ordered-dimension-any-numeric-value-pattern-op | |
| ordered-dimension-explicit-type-pattern-op |
|
ordered-dimension-explicit-type-pattern-op ::=
| ordered-dimension-fixnum-pattern-op | |
| ordered-dimension-short-float-pattern-op | |
| ordered-dimension-single-float-pattern-op | |
| ordered-dimension-double-float-pattern-op | |
| ordered-dimension-long-float-pattern-op | |
| ordered-dimension-pseudo-probability-pattern-op |
|
ordered-dimension-any-numeric-value-pattern-op ::=
| < | <= |
>= | > |
= | /= | |
| within | covers |
overlaps | |
| abuts |
starts | ends |
|
ordered-dimension-fixnum-pattern-op ::=
| <& | <=& |
>=& | >& |
=& | /=& | |
| within& | covers& |
overlaps& | |
| abuts& |
starts& | ends& |
|
ordered-dimension-short-float-pattern-op ::=
| <$& | <=$& |
>=$& | >$& |
=$& | /=$& | |
| within$& | covers$& |
overlaps$& | |
| abuts$& |
starts$& | ends$& |
|
ordered-dimension-single-float-pattern-op ::=
| <$ | <=$ |
>=$ | >$ |
=$ | /=$ | |
| within$ | covers$ |
overlaps$ | |
| abuts$ |
starts$ | ends$ |
|
ordered-dimension-double-float-pattern-op ::=
| <$$ | <=$$ |
>=$$ | >$$
| =$$ | /=$$ | |
| within$$ | covers$$ |
overlaps$$ | |
| abuts$$ |
starts$$ | ends$$ |
|
ordered-dimension-long-float-pattern-op ::=
| <$$$ | <=$$$ |
>=$$$ | >$$$ |
=$$$ | /=$$$ | |
| within$$$ | covers$$$ |
overlaps$$$ | |
| abuts$$$ |
starts$$$ | ends$$$ |
|
ordered-dimension-pseudo-probability-pattern-op ::=
| <% | <=% |
>=% | >% |
=% | /=% | |
| within% | covers% |
overlaps% | |
| abuts% | starts% | ends% |
|
enumerated-dimension-pattern-op ::=
| is | enumerated-dimension-explicit-test-pattern-op |
|
enumerated-dimension-explicit-test-pattern-op ::=
| is-eq | is-eql | is-equal |
is-equalp |
|
boolean-dimension-binary-pattern-op ::=
| eqv |
|
boolean-dimension-unary-pattern-op ::=
| true | false |
|
dimension-names ::= | dimension-name |
( dimension-name+) |
|
pattern-values ::=
| pattern-value | |
| ( pattern-value+) | |
| ( pattern-value+ .
pattern-value) | |
| #( pattern-value+) |
|
pattern-value ::=
| point | interval |
element | set |
|
interval ::= | ( start end) |
( start . end) |
#( start end) |
|
Terms
point
| | A number, infinity , or -infinity |
start | | A number or -infinity |
end | | A number or infinity |
element | | An object |
|
Description
The pattern t
matches all unit instances whose dimension values overlap the dimensional extent of at least one space instance in space-instances. The pattern :all
matches every unit instance on a space instance in space-instances, regardless of dimensional overlap. Use of find-instances with a t
or :all
pattern in production code often indicates a missed opportunity to use a more efficient do-instances-of-class, do-instances-on-space-instances, or do-sorted-instances-of-class approach (or their map-
variants).
Declared numeric and pseudo
probability pattern operators are also supported, for example:
=&
, =$&
, =$
, =$$
, =$$$
, and
=%
and within&
, within$&
,
within$
, within$$
, within$$$
,
and within%
.
See also
*find-verbose*
*use-marking*
*warn-about-unusual-requests*
do-instances-of-class
do-instances-on-space-instances
do-sorted-instances-of-class
filter-instances
find-all-instances-by-name
find-instance-by-name
find-instances-of-class
make-instances-of-class-vector
map-instances-of-class
map-instances-on-space-instances
map-sorted-instances-of-class
Declared numerics
Examples
Here are some basic examples of finding hyp
unit instances:
> (find-instances 'hyp (find-space-instance-by-path '(bb hyps))
'(and (= x 1835) (> belief .8)))
(#<hyp 319 (1835 8419) 0.91 [4..12]>
#<hyp 331 (1835 8419) 0.88 [15..30]>
#<hyp 335 (1835 8419) 0.92 [15..35]>
#<hyp 183 (1835 4791) 0.82 [0..35]>
#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 419 (1835 4791) 0.85 [5..35]>)
> (find-instances 'hyp '(bb hyps)
`(and (= x 1835)
(> belief ,(belief-of (find-instance-by-name 331 'hyp)))))
(#<hyp 319 (1835 8419) 0.91 [4..12]>
#<hyp 335 (1835 8419) 0.92 [15..35]>
#<hyp 233 (1835 4791) 0.89 [5..35]>)
> (find-instances '(hyp :no-subclasses) '(bb hyps)
'(=& (x y) (1835 8419)))
(#<hyp 319 (1835 8419) 0.91 [4..12]>
#<hyp 331 (1835 8419) 0.88 [15..30]>
#<hyp 335 (1835 8419) 0.92 [15..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (within belief (.85 .9))))
(#<hyp 331 (1835 8419) 0.88 [15..30]>
#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 419 (1835 4791) 0.85 [5..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (overlaps velocity-range (0 10))))
(#<hyp 319 (1835 8419) 0.91 [4..12]>
#<hyp 183 (1835 4791) 0.82 [0..35]>
#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 419 (1835 4791) 0.85 [5..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (overlaps velocity-range (35 40))))
(#<hyp 335 (1835 8419) 0.92 [15..35]>
#<hyp 183 (1835 4791) 0.82 [0..35]>
#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 419 (1835 4791) 0.85 [5..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (covers velocity-range (0 10))))
(#<hyp 183 (1835 4791) 0.82 [0..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (covers velocity-range (4 10))))
(#<hyp 319 (1835 8419) 0.91 [4..12]>
#<hyp 183 (1835 4791) 0.82 [0..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (within velocity-range (0 10))))
nil
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (within velocity-range (0 20))))
(#<hyp 319 (1835 8419) 0.91 [4..12]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (starts velocity-range 5)))
(#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 419 (1835 4791) 0.85 [5..35]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (ends velocity-range 30)))
(#<hyp 331 (1835 8419) 0.88 [15..30]>)
> (find-instances 'hyp '(bb hyps)
'(and (= x 1835) (abuts velocity-range (5 30))))
(#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 331 (1835 8419) 0.88 [15..30]>
#<hyp 419 (1835 4791) 0.85 [5..35]>)
> (find-instances 'hyp '(bb hyps)
'(is color :silver))
(#<hyp 183 (1835 4791) 0.82 [0..35]>
#<hyp 233 (1835 4791) 0.89 [5..35]>
#<hyp 231 (1488 7405) 0.63 [0..8]>)
> (find-instances 'hyp '(bb hyps)
'(is-eq color :yellow))
(#<hyp 331 (1835 8419) 0.88 [15..30]>
#<hyp 311 (896 388) 0.68 [0..6]>)
>
Some examples finding a word
unit instance:
> (find-instances 'word '(words) '(is character #\s))
(#<word 1>)
> (find-instances 'word '(words) '(is character #\x))
nil
>
Find word
unit instances with special characters in them:
> (find-instances 'word '(words) '(overlaps char-code (0 64)))
(#<word 1>)
>
Note
Fixnum overlaps
comparisons can result in bignum computations if the
combined intervals of the pattern and a candidate unit instance
exceeds most-positive-fixnum
.
The GBBopen Project