[Bast-commits] r3684 - DBIx-Class/0.08/trunk/lib/DBIx/Class

[jnapiorkowski at dev.catalyst.perl.org]

Author: jnapiorkowski
Date: 2007-08-16 16:23:18 +0100 (Thu, 16 Aug 2007)
New Revision: 3684

Modified:
   DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSet.pm
   DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm
Log:
-- added some documentation to ->populate to warn people about the side effects of using wantarray versus void context.
-- added some additional documentation to resultset->create


Modified: DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSet.pm
===================================================================
--- DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSet.pm	2007-08-15 23:45:32 UTC (rev 3683)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSet.pm	2007-08-16 15:23:18 UTC (rev 3684)
@@ -1251,7 +1251,7 @@
 submitting to a $resultset->create(...) method.
 
 In void context, C<insert_bulk> in L<DBIx::Class::Storage::DBI> is used
-to insert the data, as this is a faster method.
+to insert the data, as this is a faster method.  
 
 Otherwise, each set of data is inserted into the database using
 L<DBIx::Class::ResultSet/create>, and a arrayref of the resulting row
@@ -1288,6 +1288,14 @@
   
   print $ArtistOne->name; ## response is 'Artist One'
   print $ArtistThree->cds->count ## reponse is '2'
+  
+Please note an important effect on your data when choosing between void and
+wantarray context. Since void context goes straight to C<insert_bulk> in 
+L<DBIx::Class::Storage::DBI> this will skip any component that is overriding
+c<insert>.  So if you are using something like L<DBIx-Class-UUIDColumns> to 
+create primary keys for you, you will find that your PKs are empty.  In this 
+case you will have to use the wantarray context in order to create those 
+values.
 
 =cut
 
@@ -1569,6 +1577,16 @@
 
 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
 
+Example of creating a new row.
+
+  $person_rs->create({
+    name=>"Some Person",
+	email=>"somebody at someplace.com"
+  });
+  
+Example of creating a new row and also creating rows in a related C<has_many>
+or C<has_one> resultset.  Note Arrayref.
+
   $artist_rs->create(
      { artistid => 4, name => 'Manufactured Crap', cds => [ 
         { title => 'My First CD', year => 2006 },
@@ -1577,6 +1595,17 @@
      },
   );
 
+Example of creating a new row and also creating a row in a related
+C<belongs_to>resultset. Note Hashref.
+
+  $cd_rs->create({
+    title=>"Music for Silly Walks",
+	year=>2000,
+	artist => {
+	  name=>"Silly Musician",
+	}
+  });
+
 =cut
 
 sub create {

Modified: DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm
===================================================================
--- DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm	2007-08-15 23:45:32 UTC (rev 3683)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm	2007-08-16 15:23:18 UTC (rev 3684)
@@ -836,7 +836,19 @@
     [ 2, 'Indie Band' ],
     ...
   ]);
+  
+Since wantarray context is basically the same as looping over $rs->create(...) 
+you won't see any performance benefits and in this case the method is more for
+convenience. Void context sends the column information directly to storage
+using <DBI>s bulk insert method. So the performance will be much better for 
+storages that support this method.
 
+Because of this difference in the way void context inserts rows into your 
+database you need to note how this will effect any loaded components that
+override or augment insert.  For example if you are using a component such 
+as L<DBIx::Class::UUIDColumns> to populate your primary keys you MUST use 
+wantarray context if you want the PKs automatically created.
+
 =cut
 
 sub populate {