add store(), fix comments

2 files changed, 33 insertions, 6 deletions

diff --git a/it_dbi.class b/it_dbi.class
index 328e63c..3ec2978 100644
--- a/it_dbi.class
+++ b/it_dbi.class
@@ -237,7 +237,7 @@ function _connect($p = array())
 
 
 /**
- * INTERNAL: construct SQL SET clause of changed values from member vars and tags array.
+ * INTERNAL: construct SQL SET clause of changed values from tags array.
  */
 function _set($tags, $allfields = false)
 {
@@ -640,10 +640,10 @@ function iterate()
 
 
 /**
- * Insert a record into table. Values are taken from member vars and $tags.
+ * Insert a record into table. Values are taken $tags.
  * After inserting, all values are valid (record is read back).
  * Does not destroy internal state of last select() call
- * @param $tags Additional key => value pairs (these have priority over member vars)
+ * @param $tags key => value pairs to set
  */
 function insert($tags = array(), $command = "INSERT")
 {
@@ -672,7 +672,7 @@ function insert($tags = array(), $command = "INSERT")
 
 /**
  * Replace a record in a table
- * @param $tags Additional key => value pairs (these have priority over member vars)
+ * @param $tags Additional key => value pairs
  * Does not destroy internal state of last select() call
  * @see insert()
  */
@@ -683,6 +683,16 @@ function replace($tags = array())
 
 
 /**
+ * Update a record (efficiently) or create it if missing
+ * @param $tags key => value pairs to set
+ */
+function store($tags = array())
+{
+	return $tags[$this->_p['keyfield']] && $this->read($tags[$this->_p['keyfield']]) ? $this->update($tags) : $this->replace($tags);
+}
+
+
+/**
  * Update current record or a number of records given by where condition
  * @param $tags key => value pairs (these have priority over changes in member vars)
  * @param $where condition to select records to be modified (if not current record)
diff --git a/tests/it_dbi.t b/tests/it_dbi.t
index 762e81f..1ae479f 100755
--- a/tests/it_dbi.t
+++ b/tests/it_dbi.t
@@ -13,7 +13,7 @@ $dbi->query('create temporary table it_dbi_test (
 	primary key(ID)
 );');
 
-$record = new it_dbi($db + array('table' => "it_dbi_test"));
+$record  = new it_dbi($db + array('table' => "it_dbi_test"));
 
 $record->insert(array('x' => 42, 'foo' => null));
 $record->insert(array('foo' => "bar"));
@@ -236,6 +236,24 @@ foreach ($record as $dummy_rec)
 	$count++;
 is($count, 2, "Iterator reused");
 
+$record->store(array('ID' => 5, 'x' => 6));
+$record->clear();
+$record->read(5);
+is(
+	$record->x,
+	6,
+	"saving with store"
+);
+
+$record->store(array('ID' => 5, 'x' => 7));
+$record->clear();
+$record->read(5);
+is(
+	$record->x,
+	7,
+	"updating with store"
+);
+
 # Test field localization feature
 
 $dbi->query('create temporary table it_dbi_testlocalized (
@@ -271,4 +289,3 @@ is(
 	array(1, "franz"),
 	"localized field foobar_fr"
 );
-