[ Term Manipulation | Reference Manual | Alphabetic Index ]

update_struct(+StructName, +FieldList, ?OldStruct, ?NewStruct)

NewStruct is the same as OldStruct except that the fields in FieldList have been replaced
StructName
An atom (the structure name)
FieldList
A list of name:Value structures, or one such structure
OldStruct
Structure or variable
NewStruct
Variable or structure

Description

This predicate is only useful together with structure declarations. Its purpose is to allow updating a structure's fields (by creating a new, updated structure) without having to know all the fields of the structure, or its arity.

update_struct/4 creates a new structure NewStruct which is identical to another structure OldStruct, except that the fields listed in FieldList contain the values in FieldList, while all fields not mentioned in FieldList retain the same values in OldStruct and NewStruct.

update_struct/4 is usually expanded at compile time into two simple, efficient unifications (see example).

Modes and Determinism

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions

(4) instantiation fault
StructName or FieldList is a variable
(4) instantiation fault
A member of FieldList (or its tail) is insufficiently instantiated
(5) type error
StructName is not an atom, or FieldList is not a proper list
(5) type error
An Element of FieldList is not an atom:term structure
(6) out of range
StructName is not the name of a declared, visible structure
(6) out of range
A field name in FieldList is not a field of the structure denoted by StructName

Examples

    ?- local struct(person(name,address,age,salary)).
    yes.

    ?- Old = person{name:john,salary:4000,address:here,age:30},
       update_struct(person, [salary:5000,address:there], Old, New).

    Old = person(john, here, 30, 4000)
    New = person(john, there, 30, 5000)
    yes.

    ?- update_struct(person, [salary:5000], Old, New).

    Old = person(_244, _245, _246, _247)
    New = person(_244, _245, _246, 5000)
    yes.


    % Compilation: The code

    set_salary(Old, New, NewSalary) :-
    	update_struct(person, [salary:NewSalary], Old, New).

    % is compiled into

    set_salary(Old, New, NewSalary) :-
	Old = person(X1, X2, X3, _),
	New = person(X1, X2, X3, NewSalary).

See Also

struct / 1, = / 2