Author: mjevans Date: Fri Dec 18 06:51:26 2009 New Revision: 13688 Modified: dbi/trunk/DBI.pm
Log: Document new utility method sql_type_cast Modified: dbi/trunk/DBI.pm ============================================================================== --- dbi/trunk/DBI.pm (original) +++ dbi/trunk/DBI.pm Fri Dec 18 06:51:26 2009 @@ -2911,7 +2911,6 @@ See also L</visit_child_handles>. - =head2 DBI Utility Functions In addition to the DBI methods listed in the previous section, @@ -3056,6 +3055,59 @@ This function doesn't have much to do with databases, except that it can be handy to store hash values in a database. +=head3 C<sql_type_cast> + + $sts = DBI->sql_type_cast($sv, $sql_type, $flags); + +sql_type_cast attempts to cast C<$sv> to the SQL type (see L<DBI +Constants>) specified in C<$sql_type>. At present only the SQL types +C<SQL_INTEGER>, C<SQL_DOUBLE> and C<SQL_NUMERIC> are supported. + +For C<SQL_INTEGER> the effect is similar to using the value in an expression +that requires an integer. It gives the perl scalar an 'integer aspect'. +(Technically the value gains an IV, or possibly a UV or NV if the value is too +large for an IV.) + +For C<SQL_DOUBLE> the effect is similar to using the value in an expression +that requires a general numeric value. It gives the perl scalar a 'numeric +aspect'. (Technically the value gains an NV.) + +C<SQL_NUMERIC> is similar to C<SQL_INTEGER> or C<SQL_DOUBLE> but more +general and more cautious. It will look at the string first and if it +looks like an integer (that will fit in an IV or UV) it will act like +C<SQL_INTEGER>, if it looks like a floating point value it will act +like C<SQL_DOUBLE>, if it looks like neither then it will do nothing - +and thereby avoid the warnings that would be generated by +C<SQL_INTEGER> and C<SQL_DOUBLE> when given non-numeric data. + +C<$flags> may be: + +=over 4 + +=item C<DBIstcf_DISCARD_STRING> + +If this flag is specified then when the driver successfully casts the +bound perl scalar to a non-string type then the string portion of the +scalar will be discarded. + +=item C<DBIstcf_STRICT> + +If C<$sv> cannot be cast to the requested C<$sql_type> then by default +it is left untouched and no error is generated. If you specify +C<DBIstcf_STRICT> and the cast fails, this will generate an error. + +=back + +The returned C<$sts> value is: + + -2 sql_type is not handled + -1 sv is undef so unchanged + 0 sv could not be cast cleanly and DBIstcf_STRICT was used + 1 sv could not be case and DBIstcf_STRICT was not used + 2 sv was cast successfully + +This method is exported by the :utils tag and was introduced in DBI +1.611. =head2 DBI Dynamic Attributes @@ -6253,23 +6305,8 @@ From DBI 1.611, drivers can use the C<TYPE> attribute to attempt to cast the bound scalar to a perl type which more closely matches C<TYPE>. At present DBI supports C<SQL_INTEGER>, C<SQL_DOUBLE> and -C<SQL_NUMERIC>. - -For C<SQL_INTEGER> the effect is similar to using the value in an expression -that requires an integer. It gives the perl scalar an 'integer aspect'. -(Technically the value gains an IV, or possibly a UV or NV if the value is too -large for an IV.) - -For C<SQL_DOUBLE> the effect is similar to using the value in an expression -that requires a general numeric value. It gives the perl scalar a 'numeric -aspect'. (Technically the value gains an NV.) - -C<SQL_NUMERIC> is similar to C<SQL_INTEGER> or C<SQL_DOUBLE> but more general -and more cautious. It will look at the string first and if it looks like an -integer (that will fit in an IV or UV) it will act like C<SQL_INTEGER>, if it -looks like a floating point value it will act like C<SQL_DOUBLE>, if it looks -like neither then it will do nothing--and thereby avoid the warnings that would -be generated by C<SQL_INTEGER> and C<SQL_DOUBLE> when given non-numeric data. +C<SQL_NUMERIC>. See L</sql_type_cast> for details of how types are +cast. B<Other attributes for Column Binding> @@ -6277,7 +6314,7 @@ =over -=item StrictlyTyped +=item C<StrictlyTyped> If a C<TYPE> attribute is passed to bind_col, then the driver will attempt to change the bound perl scalar to match the type more @@ -6290,7 +6327,7 @@ few drivers actually supported this attribute but DBD::Oracle and DBD::ODBC should from versions 1.24. -=item DiscardString +=item C<DiscardString> When the C<TYPE> attribute is passed to L</bind_col> and the driver successfully casts the bound perl scalar to a non-string type
