SWI-Prolog -- Send methods

1.20.2 Send methods

chain ->_append: value=any|function

Append that allows for appending function objects (@arg1, @event, @receiver, class ?) to a chain without evaluating them.

See also: chain->append

chain ->add: value=any

chain->append object to chain if it is not already a member of it.

See also: - chain->member
- chain->append

chain ->after: first=any, second=any

Succeeds if the first occurrence of the first argument is after the first occurrence of the second argument. Example:

?- new(@ch, chain(aap, noot, mies)).
?- send(@ch, after, noot, aap)		--> yes
?- send(@ch, after, aap, mies)		--> no

Fails if one of the arguments is not in the chain.

See also: chain->before

chain ->append: value=any

Append argument at the end of the chain. Although chains are represented as single linked lists, append is efficient because chains maintain a pointer to the last cell.

Note that chains may contain duplicates.

See also: - chain->add
- chain->_append

chain ->before: first=any, second=any

Succeeds if the first occurrence of the first argument is before the first occurrence of the second argument. See chain->after.

See also: - chain->move_before
- chain->after

chain ->cell_value: cell_reference=int, value=any

Set the value of specified cell. The first argument is the reference returned by chain<-head_cell or chain<-next_cell.

One should try to avoid using this function.

See also: - chain<-cell_value
- chain<-head_cell
- chain<-next_cell

chain ->clear:

Remove all elements from the chain. Note that this implies that elements that have no further references are destroyed. The other elements are not affected.

chain ->current: value=any*

Replace the value of the current cell with the argument.

See also: topic Current

chain ->current_no: index=int

Make the nth (1-based) cell current. When the argument is 0, there is no current cell.

Diagnostics: Fails without modifiying the current element if the index is out of range.

See also: - topic Current
- chain<-nth1

chain ->delete: value=any

Delete the first occurrence of object from the chain. Fails if there is no such object. Note that objects are compared by their object identity; not by their contents. Hence, the following fails because the second point is a different instance.

?- new(@ch, chain(point(6,6))).
Yes
?- send(@ch, delete, point(6,6)).
No

See also: chain->delete_all

chain ->delete_all: value=any

Delete all elements of the chain that are equal to the argument. Always succeeds. See also chain->delete.

See also: chain->delete

chain ->delete_current:

Delete the current cell.

See also: topic Current

chain ->delete_head:

Delete the first element of the chain. See also chain<-head and chain<-delete_head.

Diagnostics: Fails if the chain is empty.

chain ->delete_tail:

Delete the last element of the chain. Note that chains are single linked lists and thus deleting the last implies traversing the entire list.

Diagnostics: Fails if the chain is empty.

chain ->empty:

Succeeds if the chain has no elements. Intended as a test method.

chain ->equal: chain

Succeeds if both chains have the same elements. For convenience reasons, the type is defined the include @default and @nil and thus this method fails silently when a chain is compared to one of these constants and fails with a type-error if the argument is neither one of these constants, nor an instance of class chain or a subclass thereof.

chain ->find: test=code

Successively executes code on all elements of the chain. Succeeds, setting chain<-current if code is executed with success. Fails otherwise. Arguments:

@arg1 The (current) element

@arg2 1-based index of element

New code should consider using chain<-find, which avoids the usage of chain<-current.

See also: - chain->for_all
- chain<-find

chain ->for_all: action=code, safe=[bool]

This method invokes its argument code object on all elements of the chain. During the execution the following argument is bound:

@arg1 Current element.

@arg2 Index of the element (1-based)

The iteration stops with failure if the execution of code fails for some element of the chain.

In the example below we print the elements of a chain on the terminal:

?- new(@ch, chain(hello, world)).
?- send(@ch, for_all, message(@pce, write_ln, @arg1)).
hello
world

If the safe argument is @on (default), the elements of the chain are first copied to a local array and existence of the objects in the elements is tested prior to executing the code object. This implies that the chain may be modified by the execution of the method and new elements will not be seen. If this argument is @off this method iterates over the chain itself. In this case it is not allowed to modify the chain.

Defaults: By default this operation is caried-out safe (= @on).

See also: - chain<-find_all
- chain<-find
- chain->find
- chain->for_some
- hash_table->for_all
- device->for_all

chain ->for_some: action=code, safe=[bool]

Similar to chain->for_all, but continues the iteration even if code fails to execute for some element. Always succeeds. Forwarded arguments:

@arg1		element
@arg2		1-based index of element

See also: chain->for_all

chain ->initialise: member=any ...

Create a chain from an initial list of elements.

chain ->insert: value=any

Insert argument before chain<-current. Use of chain<-current is discouraged and new code must consider using chain->insert_before.

See also: - chain->move_before
- topic Current

chain ->insert_after: value=any, after=any*

@see chain->move_before

chain ->insert_before: value=any, before=any

Insert first before second object. If the second object is not a chain<-member of the chain, value is chain->append’ed.

See also chain->move_before.

See also: - chain->move_before
- node->move_after

chain ->move_before: value=any, before=any

Move the first member of the chain to be just before the second. Fails if either of the elements is not a chain->member or they are equal. To move an element to the start of the chain, you may use either of:

?- ignore(send(Ch, move_before, Element, Ch?head)).
?- send(Ch, move_after, Element).

Diagnostics: Fails silently if either argument is not a chain->member of the chain.

See also: - chain->insert
- chain->before
- chain->insert_after
- chain->move_after

chain ->sort: compare=[code|function], unique=[bool]

Sort the elements in the chain. Two elements are compared by examining the return status of the code object. Both @arg1 and @arg2 are bound to some element of the chain. Execution of the code is supposed to succeed if @arg1 must be before @arg2 in the sorted chain. If code is a function object, the return status is interpreted as follows:

integer smaller then 0 or the atom smaller @arg1 must be before @arg2
0 or the atom equal Both elements are equal (neither is deleted, but their order is undefined).
anything else @arg1 must be after @arg2
Common code objects to use are the arithmetic comparison objects and messages invoking a string comparison method. Examples:

Sort a chain of integers, lowest first:
```
send(Chain, sort, @arg1 < @arg2).
```
Sort a chain of char_array objects, alphabetically lowest first:
```
send(Chain, sort, ?(@arg1, compare, @arg2)).
```
If compare code is omitted, the contents of the chain is sorted on alphabetically on their object<-print_name.

If unique equals @on, duplicates (i.e. pairs of objects for which executing the comparison yields equal) will be removed. Default is not to remove duplicates. See also chain->unique.

NOTE: When sorting with a non-function, the result of comparing two element is a boolean and cannot express equal. chain->sort yields an undefined result if the chain contains two or more element for which code->forward and code->forward yield the same result. This undefined behaviour can include a fatal error.

See also
- char_array<-compare
- char_array->smaller
- char_array->larger
- class binary_condition
- vector->sort

chain ->subtract: chain

Delete all elements in the argument from the receiving chain. See also chain->delete_all.

chain ->unique:

Remove all duplicates from chain. Objects are compared by reference. See also chain->sort and chain->add.

chain ->unlink:

First invokes chain->clear to remove the cells.

@arg1	The (current) element
@arg2	1-based index of element

@arg1	Current element.
@arg2	Index of the element (1-based)