DataMapper: does set_join_field() create a new record or only update an existing one?

[eluser]Genki1[/eluser]
Hi WanWizard,

When using set_join_field(), it seems to only update the join table if the two records have already been related with a save(). Is that correct?

After doing this, the join table has the expected new record:

Code:

$u = new User(1);
$b = new Book(99);
$u->save($b);
$u->set_join_field($b, 'value', TRUE);

After doing this, the join table does not contain the expected record:

Code:

$u = new User(1);
$b = new Book(99);
$u->set_join_field($b, 'value', TRUE);

The relationships have been properly defined in the models.
Is the behavior I'm encountering correct?

(BTW, the manual for set_join_field() does not explicitly state whether a save() must be issued after set_join_field(). I checked the library and see that the update is performed, but it would be helpful to state so in the documentation.)