GBBopen 1.5 Reference -- find-instance-by-name

find-instance-by-name

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

Purpose
Retrieve a unit instance by its instance 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`)
errorp		A generalized boolean (default is `nil`)
unit-instance		A unit instance or `nil`

Returns
The first unit instance found of the specified class(es) that has the specified instance-name if one exists; nil otherwise.

Errors
If errorp is true, an error is signaled if no unit instance is found.

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. When strings are used as the names of unit instances, equal (case sensitive) or equalp (case insensitive) should be specified as the comparison function in the unit classes of those unit instances.

Example
Find the hyp unit instance 419:

  > (find-instance-by-name 419 'hyp)
  #<hyp 419 (1835 4791) 0.85 [5..35]>
  > (find-instance-by-name 0 'hyp)
  nil
  > (find-instance-by-name 0 'hyp 't)
  No unit instance named 0 of class hyp was found.
  >

REPL Note
Find-instance-by-name can be invoked using the REPL command:

  :fi instance-name [unit-classes-specifier [errorp]]

which sets = to the found unit instance.

The GBBopen Project

find-instance-by-name