GBBopen 1.5 Reference -- link-setf

link-setf

link-setf

link-slot-place unit-instance-or-instances => unit-instance-or-instances

[Macro]

Purpose
Set link-slot-place to be precisely unit-instance-or-instances links between unit instance and unit-instance-or-instances.

Package :gbbopen

Module :gbbopen-core

Arguments and values

link-slot-place		A form which is suitable for use as a generalized reference to a link slot
unit-instance-or-instances		A unit instance, a link-pointer object, or a list of unit instances and link-pointer objects

Returns
The supplied unit-instance-or-instances.

Events
An unlink-event is signaled for:

all pointers that are removed from the specified link-slot-place
each inverse pointer of the link that is removed-from another unit instance

A link-event is signaled for:

all pointers that are added to the specified link-slot-place (unlike linkf, this event is signaled even if no new pointers were added to link-slot-place)
each inverse pointer of the link that is added to another unit instance

Description
Any existing links in link-slot-place that do not involve unit-instance-or-instances are unlinked. Existing links that are also specified as link-pointer objects in unit-instance-or-instances are replaced with the new link-pointer objects. Then links to any additional unit instances in unit-instance-or-instances are added.

The order of the specified unit-instance-or-instances is maintained when settting the value of link-slot-place, if no :sort-function was specified as a link-slot-option in the unit-class definition for that link slot. Any duplicates in unit-instance-or-instances are removed, but the order of the remaining elements will be the same as the order in which they appeared in unit-instance-or-instances.

Examples
Set the supporting-hyps link slot of the hyp unit instance to the unit instances in supporting-hyps:

  > (link-setf (supporting-hyps-of unit-instance) supporting-hyps)
  #<hyp 231 (1488 7405) 0.63 [0..8]>
  >

Note that, when a link pointer to hyp 231 is already present in a link slot, adding a link-pointer-object link to that same hyp unit instance replaces the existing link pointer:

  > (supporting-hyps-of unit-instance)
  (#<hyp 231 (1488 7405) 0.63 [0..8]>)
  > (link-setf (supporting-hyps-of unit-instance) 
           (make-instance 'link-ptr-with-value
               :link-instance support-hyp
               :value 0.9))
  #<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>
  > (supporting-hyps-of unit-instance)
  (#<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>)
  > (value-of *)
  0.9
  >

Replace the existing link-pointer-object pointer with one that has a different value:

  > (supporting-hyps-of unit-instance)
  (#<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>)
  > (link-setf (supporting-hyps-of unit-instance) 
           (make-instance 'link-ptr-with-value
               :link-instance support-hyp
               :value 0.94))
  #<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>
  > (supporting-hyps-of unit-instance)
  (#<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>)
  > (value-of *)
  0.94
  >

Of course, a value change can also be done directly in an existing link-pointer object:

  > (supporting-hyps-of unit-instance)
  (#<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>)
  > (setf (value-of *) 0.96)
  0.96
  > (supporting-hyps-of unit-instance)
  (#<link-ptr-with-value #<hyp 231 (1488 7405) 0.63 [0..8]>)
  > (value-of *)
  0.96
  >

Note
The form (link-setf link-slot-place nil) is semantically equivalent to (unlinkf-all link-slot-place). However, using unlinkf-all is preferable stylistically and slightly faster.

The GBBopen Project

link-setf