<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Module: ActiveRecord::Calculations::ClassMethods</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Module</strong></td>
<td class="class-name-in-header">ActiveRecord::Calculations::ClassMethods</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../../files/lib/active_record/calculations_rb.html">
lib/active_record/calculations.rb
</a>
<br />
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000383">average</a>
<a href="#M000387">calculate</a>
<a href="#M000388">construct_count_options_from_args</a>
<a href="#M000382">count</a>
<a href="#M000385">maximum</a>
<a href="#M000384">minimum</a>
<a href="#M000386">sum</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000383" class="method-detail">
<a name="M000383"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000383.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000383.html');return false;">
<span class="method-name">average</span><span class="method-args">(column_name, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Calculates the <a href="ClassMethods.html#M000383">average</a> value on a
given column. The value is returned as a float, or <tt>nil</tt> if
there‘s no row. See <tt><a
href="ClassMethods.html#M000387">calculate</a></tt> for examples with
options.
</p>
<pre>
Person.average('age') # => 35.8
</pre>
</div>
</div>
<div id="method-M000387" class="method-detail">
<a name="M000387"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000387.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000387.html');return false;">
<span class="method-name">calculate</span><span class="method-args">(operation, column_name, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
This calculates aggregate values in the given column. Methods for <a
href="ClassMethods.html#M000382">count</a>, <a
href="ClassMethods.html#M000386">sum</a>, <a
href="ClassMethods.html#M000383">average</a>, <a
href="ClassMethods.html#M000384">minimum</a>, and <a
href="ClassMethods.html#M000385">maximum</a> have been added as shortcuts.
Options such as <tt>:conditions</tt>, <tt>:order</tt>, <tt>:group</tt>,
<tt>:having</tt>, and <tt>:joins</tt> can be passed to customize the query.
</p>
<p>
There are two basic forms of output:
</p>
<pre>
* Single aggregate value: The single value is type cast to Fixnum for COUNT, Float for AVG, and the given column's type for everything else.
* Grouped values: This returns an ordered hash of the values and groups them by the <tt>:group</tt> option. It takes either a column name, or the name
of a belongs_to association.
values = Person.maximum(:age, :group => 'last_name')
puts values["Drake"]
=> 43
drake = Family.find_by_last_name('Drake')
values = Person.maximum(:age, :group => :family) # Person belongs_to :family
puts values[drake]
=> 43
values.each do |family, max_age|
...
end
</pre>
<p>
Options:
</p>
<ul>
<li><tt>:conditions</tt> - An SQL fragment like "administrator = 1"
or [ "user_name = ?", username ]. See conditions in the intro to
<a href="../Base.html">ActiveRecord::Base</a>.
</li>
<li><tt>:include</tt>: Eager loading, see Associations for details. Since
calculations don‘t load anything, the purpose of this is to access
fields on joined tables in your conditions, order, or group clauses.
</li>
<li><tt>:joins</tt> - An SQL fragment for additional joins like "LEFT JOIN
comments ON comments.post_id = id". (Rarely needed). The records will
be returned read-only since they will have attributes that do not
correspond to the table‘s columns.
</li>
<li><tt>:order</tt> - An SQL fragment like "created_at DESC, name"
(really only used with GROUP BY calculations).
</li>
<li><tt>:group</tt> - An attribute name by which the result should be grouped.
Uses the GROUP BY SQL-clause.
</li>
<li><tt>:select</tt> - By default, this is * as in SELECT * FROM, but can be
changed if you for example want to do a join, but not include the joined
columns.
</li>
<li><tt>:distinct</tt> - Set this to true to make this a distinct calculation,
such as SELECT COUNT(DISTINCT posts.id) …
</li>
</ul>
<p>
Examples:
</p>
<pre>
Person.calculate(:count, :all) # The same as Person.count
Person.average(:age) # SELECT AVG(age) FROM people...
Person.minimum(:age, :conditions => ['last_name != ?', 'Drake']) # Selects the minimum age for everyone with a last name other than 'Drake'
Person.minimum(:age, :having => 'min(age) > 17', :group => :last_name) # Selects the minimum age for any family without any minors
Person.sum("2 * age")
</pre>
</div>
</div>
<div id="method-M000382" class="method-detail">
<a name="M000382"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000382.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000382.html');return false;">
<span class="method-name">count</span><span class="method-args">(*args)</span>
</a>
</div>
<div class="method-description">
<p>
Count operates using three different approaches.
</p>
<ul>
<li>Count all: By not passing any parameters to <a
href="ClassMethods.html#M000382">count</a>, it will return a <a
href="ClassMethods.html#M000382">count</a> of all the rows for the model.
</li>
<li>Count using column: By passing a column name to <a
href="ClassMethods.html#M000382">count</a>, it will return a <a
href="ClassMethods.html#M000382">count</a> of all the rows for the model
with supplied column present
</li>
<li>Count using options will find the row <a
href="ClassMethods.html#M000382">count</a> matched by the options used.
</li>
</ul>
<p>
The third approach, <a href="ClassMethods.html#M000382">count</a> using
options, accepts an option hash as the only parameter. The options are:
</p>
<ul>
<li><tt>:conditions</tt>: An SQL fragment like "administrator = 1" or
[ "user_name = ?", username ]. See conditions in the intro to <a
href="../Base.html">ActiveRecord::Base</a>.
</li>
<li><tt>:joins</tt>: Either an SQL fragment for additional joins like
"LEFT JOIN comments ON comments.post_id = id" (rarely needed) or
named associations in the same form used for the <tt>:include</tt> option,
which will perform an INNER JOIN on the associated table(s). If the value
is a string, then the records will be returned read-only since they will
have attributes that do not correspond to the table‘s columns. Pass
<tt>:readonly => false</tt> to override.
</li>
<li><tt>:include</tt>: Named associations that should be loaded alongside using
LEFT OUTER JOINs. The symbols named refer to already defined associations.
When using named associations, <a
href="ClassMethods.html#M000382">count</a> returns the number of DISTINCT
items for the model you‘re counting. See eager loading under
Associations.
</li>
<li><tt>:order</tt>: An SQL fragment like "created_at DESC, name"
(really only used with GROUP BY calculations).
</li>
<li><tt>:group</tt>: An attribute name by which the result should be grouped.
Uses the GROUP BY SQL-clause.
</li>
<li><tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be
changed if you, for example, want to do a join but not include the joined
columns.
</li>
<li><tt>:distinct</tt>: Set this to true to make this a distinct calculation,
such as SELECT COUNT(DISTINCT posts.id) …
</li>
<li><tt>:from</tt> - By default, this is the table name of the class, but can
be changed to an alternate table name (or even the name of a database
view).
</li>
</ul>
<p>
Examples for counting all:
</p>
<pre>
Person.count # returns the total count of all people
</pre>
<p>
Examples for counting by column:
</p>
<pre>
Person.count(:age) # returns the total count of all people whose age is present in database
</pre>
<p>
Examples for <a href="ClassMethods.html#M000382">count</a> with options:
</p>
<pre>
Person.count(:conditions => "age > 26")
Person.count(:conditions => "age > 26 AND job.salary > 60000", :include => :job) # because of the named association, it finds the DISTINCT count using LEFT OUTER JOIN.
Person.count(:conditions => "age > 26 AND job.salary > 60000", :joins => "LEFT JOIN jobs on jobs.person_id = person.id") # finds the number of rows matching the conditions and joins.
Person.count('id', :conditions => "age > 26") # Performs a COUNT(id)
Person.count(:all, :conditions => "age > 26") # Performs a COUNT(*) (:all is an alias for '*')
</pre>
<p>
Note: <tt>Person.count(:all)</tt> will not work because it will use
<tt>:all</tt> as the condition. Use Person.count instead.
</p>
</div>
</div>
<div id="method-M000385" class="method-detail">
<a name="M000385"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000385.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000385.html');return false;">
<span class="method-name">maximum</span><span class="method-args">(column_name, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Calculates the <a href="ClassMethods.html#M000385">maximum</a> value on a
given column. The value is returned with the same data type of the column,
or <tt>nil</tt> if there‘s no row. See <tt><a
href="ClassMethods.html#M000387">calculate</a></tt> for examples with
options.
</p>
<pre>
Person.maximum('age') # => 93
</pre>
</div>
</div>
<div id="method-M000384" class="method-detail">
<a name="M000384"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000384.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000384.html');return false;">
<span class="method-name">minimum</span><span class="method-args">(column_name, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Calculates the <a href="ClassMethods.html#M000384">minimum</a> value on a
given column. The value is returned with the same data type of the column,
or <tt>nil</tt> if there‘s no row. See <tt><a
href="ClassMethods.html#M000387">calculate</a></tt> for examples with
options.
</p>
<pre>
Person.minimum('age') # => 7
</pre>
</div>
</div>
<div id="method-M000386" class="method-detail">
<a name="M000386"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000386.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000386.html');return false;">
<span class="method-name">sum</span><span class="method-args">(column_name, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Calculates the <a href="ClassMethods.html#M000386">sum</a> of values on a
given column. The value is returned with the same data type of the column,
0 if there‘s no row. See <tt><a
href="ClassMethods.html#M000387">calculate</a></tt> for examples with
options.
</p>
<pre>
Person.sum('age') # => 4562
</pre>
</div>
</div>
<h3 class="section-bar">Protected Instance methods</h3>
<div id="method-M000388" class="method-detail">
<a name="M000388"></a>
<div class="method-heading">
<a href="ClassMethods.src/M000388.html" target="Code" class="method-signature"
onclick="popupCode('ClassMethods.src/M000388.html');return false;">
<span class="method-name">construct_count_options_from_args</span><span class="method-args">(*args)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d51872cc0e1fdee944d71993f94ac764
>
files
>
239
