GBBopen 1.5 Reference -- find-all-instances-by-name

find-all-instances-by-name

find-all-instances-by-name instance-name &optional unit-class-specifier => unit-instances [Function]

Purpose
Retrieve unit instances with a given name.

Package :gbbopen

Module :gbbopen-core

Arguments and values

instance-name		The instance name for the retrieval
unit-class-specifier		An extended unit-class specification (see below; default is `t`)
unit-instances		A proper list of unit instances

Returns
A list of the unit instances with the specified name of the specified classes if any exist; nil otherwise.

Detailed syntax

`unit-class-specifier` ::=	`atomic-unit-class` \| `(atomic-unit-class subclassing-specifier)` \| `t`

`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.

Description
The :instance-name-comparison-test function (eq, eql, equal, or equalp) specified in define-unit-class is used to match instance-name with the unit-instance's instance name. If you are using strings as the names of unit instances, you should specify equal (case sensitive) or equalp (case insensitive) as the comparison function in the unit classes of those unit instances.

Examples
Find all unit instances (of any unit class) that are named 419:

  > (find-instances-by-name 419 't)
  (#<hyp 419 (1835 4791) 0.85 [5..35]>)
  >

Find all unit instances (of any unit class) that are named 419:

  > (find-instances-by-name 419 '(hyp :plus-subclasses))
  (#<hyp 419 (1835 4791) 0.85 [5..35]>)
  >

or simply:

  > (find-instances-by-name 419 '(hyp +))
  (#<hyp 419 (1835 4791) 0.85 [5..35]>)
  >

The GBBopen Project

find-all-instances-by-name