# Orphan records

Arity/Prolog32 provides database predicates which provide additional flexibility in organizing records. For example, a spatial index such as R-trees could be built using these predicates.

In addition to the predicates defined in this section, Arity/Prolog32 provides predicates for the encoding and decoding of Prolog terms using the same mechanism as is used for the internal database. Refer to the Term structure conversions section for a description of these predicates.

All orphan predicates operate within the current workspace.

record_orphan(+Term, -Ref)

record_orphan(+Partition, +Term, -Ref)

The record_orphan/2 and record_orphan/3 predicates store Term in the database and return a database reference Ref. The stored term may be retrieved using instance/2 but otherwise is unaccessible. The arity 3 version allows the term to be explicitly associated with a partition, providing some control over database locality of reference with other stored records.

ref_copy(+Ref, -Ref1)

The ref_copy/2 predicate directly copies the Term stored under Ref to create a new database record with database Ref1. The ref_copy/2 predicate is functionally equivalent to using instance/2 and record_orphan/2 but is more efficient, especially for large terms.

move_ref(+Ref, +TargetRef, +Direction)

The move_ref/3 record is used to modify the placement of a database term in doubly-linked lists. The database term associated with Ref, and its access using Ref is unchanged.

If Ref initially exists within a sequence of doubly-linked records, it is removed and the chain is rejoined if their are records, or is deleted if the record was the only record.

If TargetRef equals ~0 (the null database reference) then move_ref creates an orphan record, and you should provide 0 to the Direction argument.

If TargetRef is a database reference then Direction indicates whether the Ref should be added before or after the TargetRef in the doubly-linked chain of TargetRef (or creating a doubly linked chain if TargetRef is an orphan). If Direction is equal to the integer 0, then Ref is inserted after TargetRef. If Direction is equal to 1, then Ref is inserted before TargetRef.

The following example illustrates moving two database records from a sequence of records stored under a key to create a new sequence with no key. Note that the first record in the constructed sequence has no previous reference and the last record has no next reference.

?- recordz(aa, 1, R).
R = ~402FE0
yes
?- recordz(aa, 2, R).
R = ~402FDC
yes
?- recordz(aa, 3, R).
R = ~402F1C
yes

?- move_ref(~402F1C, ~0, 0).    % create an orphan
yes

?- recorded(aa, X, Y).
X = 1
Y = ~402FE0 ->;
X = 2
Y = ~402FDC ->;
no

?- move_ref(~402fe0, ~402F1C, 1).    % create a 2 record chain
yes

?- recorded(aa, X, Y).
X = 2
Y = ~402FDC ->;
no

?- X = ~402fe0, instance(X, Y), nref(X, Z), instance(Z, W).
X = ~402FE0
Y = 1
Z = ~402F1C
W = 3
yes

?- X = ~402fe0, instance(X, Y), pref(X, Z).
no

?- move_ref(~402fe0, ~402F1C, 0).    % swap the order in the chain
yes

?- X = ~402fe0, instance(X, Y), pref(X, Z), instance(Z, W).
X = ~402FE0
Y = 1
Z = ~402F1C
W = 3
yes

?- X = ~402fe0, instance(X, Y), nref(X, Z).
no