10.23.4 Accessing and Modifying Foreign Term Contents

Prolog can get or modify the contents of a foreign term with the procedures

     get_contents(+Datum, ?Part, ?Value)
     put_contents(+Datum, +Part, +Value).

It can also get a pointer to a field or element of a foreign term with the procedure

     get_address(+Datum, ?Part, ?Value).

For all three of these, Datum must be a foreign term, and Part specifies what part of Datum Value is. If Datum is an array, Part should be an integer index into the array, where 0 is the first element. For a pointer, Part should be the atom contents and Value will be what the pointer points to. For a struct, Part should be a field name, and Value will be the contents of that field. In the case of get_contents/3 and get_address/3, if Part is unbound, get_contents/3 will backtrack through all the valid parts of Datum, binding both Part and Value. A C programmer might think of the following pairs as corresponding to each other:

     Prolog: get_contents(Foo, Bar, Baz)
          C: Baz = Foo->Bar
     
     Prolog: put_contents(Foo, Bar, Baz)
          C: Foo->Bar = Baz
     
     Prolog: get_address(Foo, Bar, Baz)
          C: Baz = &Foo->Bar.

The hitch is that only atomic and pointer types can be got and put by get_contents/3 and put_contents/3. This is because Prolog can only hold pointers to C structures, not the structures themselves. This isn't quite as bad as it might seem, though, since usually structures contain pointers to other structures, anyway. When a structure directly contains another structure, Prolog can get a pointer to it with get_address/3.