Permalink
Browse files

update AS/core_ext docs [ci skip]

  • Loading branch information...
1 parent f4e1805 commit 794a70f94485fb64ed1c49ba8532895306e2001c Francesco Rodriguez committed Sep 12, 2012
Showing with 121 additions and 113 deletions.
  1. +3 −3 activesupport/lib/active_support/core_ext/array/conversions.rb
  2. +2 −2 activesupport/lib/active_support/core_ext/array/extract_options.rb
  3. +2 −2 activesupport/lib/active_support/core_ext/array/grouping.rb
  4. +0 −1 activesupport/lib/active_support/core_ext/array/uniq_by.rb
  5. +2 −2 activesupport/lib/active_support/core_ext/array/wrap.rb
  6. +3 −3 activesupport/lib/active_support/core_ext/class/attribute.rb
  7. +2 −2 activesupport/lib/active_support/core_ext/date/calculations.rb
  8. +1 −1 activesupport/lib/active_support/core_ext/date/conversions.rb
  9. +3 −2 activesupport/lib/active_support/core_ext/date/zones.rb
  10. +31 −24 activesupport/lib/active_support/core_ext/date_time/calculations.rb
  11. +4 −3 activesupport/lib/active_support/core_ext/date_time/conversions.rb
  12. +6 −5 activesupport/lib/active_support/core_ext/date_time/zones.rb
  13. +6 −5 activesupport/lib/active_support/core_ext/enumerable.rb
  14. +1 −1 activesupport/lib/active_support/core_ext/hash/conversions.rb
  15. +2 −2 activesupport/lib/active_support/core_ext/hash/deep_merge.rb
  16. +0 −1 activesupport/lib/active_support/core_ext/hash/except.rb
  17. +3 −5 activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
  18. +7 −7 activesupport/lib/active_support/core_ext/hash/keys.rb
  19. +2 −2 activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
  20. +6 −2 activesupport/lib/active_support/core_ext/hash/slice.rb
  21. +0 −2 activesupport/lib/active_support/core_ext/integer/inflections.rb
  22. +11 −9 activesupport/lib/active_support/core_ext/integer/time.rb
  23. +6 −5 activesupport/lib/active_support/core_ext/kernel/reporting.rb
  24. +0 −1 activesupport/lib/active_support/core_ext/module/anonymous.rb
  25. +0 −2 activesupport/lib/active_support/core_ext/module/introspection.rb
  26. +3 −3 activesupport/lib/active_support/core_ext/string/filters.rb
  27. +0 −1 activesupport/lib/active_support/core_ext/string/output_safety.rb
  28. +12 −12 activesupport/lib/active_support/core_ext/time/conversions.rb
  29. +3 −3 activesupport/lib/active_support/core_ext/time/zones.rb
@@ -142,7 +142,7 @@ def to_formatted_s(format = :default)
#
# Otherwise the root element is "objects":
#
- # [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
+ # [{ foo: 1, bar: 2}, { baz: 3}].to_xml
#
# <?xml version="1.0" encoding="UTF-8"?>
# <objects type="array">
@@ -164,7 +164,7 @@ def to_formatted_s(format = :default)
#
# To ensure a meaningful root element use the <tt>:root</tt> option:
#
- # customer_with_no_projects.projects.to_xml(:root => "projects")
+ # customer_with_no_projects.projects.to_xml(root: 'projects')
#
# <?xml version="1.0" encoding="UTF-8"?>
# <projects type="array"/>
@@ -174,7 +174,7 @@ def to_formatted_s(format = :default)
#
# The +options+ hash is passed downwards:
#
- # Message.all.to_xml(:skip_types => true)
+ # Message.all.to_xml(skip_types: true)
#
# <?xml version="1.0" encoding="UTF-8"?>
# <messages>
@@ -17,8 +17,8 @@ class Array
# args.extract_options!
# end
#
- # options(1, 2) # => {}
- # options(1, 2, :a => :b) # => {:a=>:b}
+ # options(1, 2) # => {}
+ # options(1, 2, a: :b) # => {:a=>:b}
def extract_options!
if last.is_a?(Hash) && last.extractable_options?
pop
@@ -83,8 +83,8 @@ def in_groups(number, fill_with = nil)
# Divides the array into one or more subarrays based on a delimiting +value+
# or the result of an optional block.
#
- # [1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]]
- # (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]]
+ # [1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]]
+ # (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]]
def split(value = nil, &block)
inject([[]]) do |results, element|
if block && block.call(element) || value == element
@@ -4,7 +4,6 @@ class Array
# Returns a unique array based on the criteria in the block.
#
# [1, 2, 3, 4].uniq_by { |i| i.odd? } # => [1, 2]
- #
def uniq_by(&block)
ActiveSupport::Deprecation.warn 'uniq_by is deprecated. Use Array#uniq instead', caller
uniq(&block)
@@ -22,8 +22,8 @@ class Array
#
# The last point is particularly worth comparing for some enumerables:
#
- # Array(:foo => :bar) # => [[:foo, :bar]]
- # Array.wrap(:foo => :bar) # => [{:foo => :bar}]
+ # Array(foo: :bar) # => [[:foo, :bar]]
+ # Array.wrap(foo: :bar) # => [{:foo => :bar}]
#
# There's also a related idiom that uses the splat operator:
#
@@ -57,16 +57,16 @@ class Class
# object.setting # => false
# Base.setting # => true
#
- # To opt out of the instance reader method, pass :instance_reader => false.
+ # To opt out of the instance reader method, pass <tt>instance_reader: false</tt>.
#
# object.setting # => NoMethodError
# object.setting? # => NoMethodError
#
- # To opt out of the instance writer method, pass :instance_writer => false.
+ # To opt out of the instance writer method, pass <tt>instance_writer: false</tt>.
#
# object.setting = false # => NoMethodError
#
- # To opt out of both instance methods, pass :instance_accessor => false.
+ # To opt out of both instance methods, pass <tt>instance_accessor: false</tt>.
def class_attribute(*attrs)
options = attrs.extract_options!
instance_reader = options.fetch(:instance_accessor, true) && options.fetch(:instance_reader, true)
@@ -86,8 +86,8 @@ def advance(options)
# Returns a new Date where one or more of the elements have been changed according to the +options+ parameter.
# The +options+ parameter is a hash with a combination of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>.
#
- # Date.new(2007, 5, 12).change(:day => 1) # => Date.new(2007, 5, 1)
- # Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12)
+ # Date.new(2007, 5, 12).change(day: 1) # => Date.new(2007, 5, 1)
+ # Date.new(2007, 5, 12).change(year: 2005, month: 1) # => Date.new(2005, 1, 12)
def change(options)
::Date.new(
options.fetch(:year, year),
@@ -43,7 +43,7 @@ class Date
#
# # config/initializers/time_formats.rb
# Date::DATE_FORMATS[:month_and_year] = '%B %Y'
- # Date::DATE_FORMATS[:short_ordinal] = lambda { |date| date.strftime("%B #{date.day.ordinalize}") }
+ # Date::DATE_FORMATS[:short_ordinal] = ->(date) { date.strftime("%B #{date.day.ordinalize}") }
def to_formatted_s(format = :default)
if formatter = DATE_FORMATS[format]
if formatter.respond_to?(:call)
@@ -2,8 +2,9 @@
require 'active_support/core_ext/time/zones'
class Date
- # Converts Date to a TimeWithZone in the current zone if Time.zone or Time.zone_default
- # is set, otherwise converts Date to a Time via Date#to_time
+ # Converts Date to a TimeWithZone in the current zone if <tt>Time.zone</tt> or
+ # <tt>Time.zone_default</tt> is set, otherwise converts Date to a Time via
+ # Date#to_time.
def to_time_in_current_zone
if ::Time.zone
::Time.zone.local(year, month, day)
@@ -9,35 +9,40 @@ def local_offset
::Time.local(2012).utc_offset.to_r / 86400
end
- # Returns <tt>Time.zone.now.to_datetime</tt> when <tt>Time.zone</tt> or <tt>config.time_zone</tt> are set, otherwise returns <tt>Time.now.to_datetime</tt>.
+ # Returns <tt>Time.zone.now.to_datetime</tt> when <tt>Time.zone</tt> or
+ # <tt>config.time_zone</tt> are set, otherwise returns
+ # <tt>Time.now.to_datetime</tt>.
def current
::Time.zone ? ::Time.zone.now.to_datetime : ::Time.now.to_datetime
end
end
- # Tells whether the DateTime object's datetime lies in the past
+ # Tells whether the DateTime object's datetime lies in the past.
def past?
self < ::DateTime.current
end
- # Tells whether the DateTime object's datetime lies in the future
+ # Tells whether the DateTime object's datetime lies in the future.
def future?
self > ::DateTime.current
end
- # Seconds since midnight: DateTime.now.seconds_since_midnight
+ # Seconds since midnight: DateTime.now.seconds_since_midnight.
def seconds_since_midnight
sec + (min * 60) + (hour * 3600)
end
- # Returns a new DateTime where one or more of the elements have been changed according to the +options+ parameter. The time options
- # (<tt>:hour</tt>, <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and
- # minute is passed, then sec is set to 0. The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>,
- # <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>.
+ # Returns a new DateTime where one or more of the elements have been changed
+ # according to the +options+ parameter. The time options (<tt>:hour</tt>,
+ # <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is
+ # passed, then minute and sec is set to 0. If the hour and minute is passed,
+ # then sec is set to 0. The +options+ parameter takes a hash with any of these
+ # keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>,
+ # <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>.
#
- # DateTime.new(2012, 8, 29, 22, 35, 0).change(:day => 1) # => DateTime.new(2012, 8, 1, 22, 35, 0)
- # DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1) # => DateTime.new(1981, 8, 1, 22, 35, 0)
- # DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0) # => DateTime.new(1981, 8, 29, 0, 0, 0)
+ # DateTime.new(2012, 8, 29, 22, 35, 0).change(day: 1) # => DateTime.new(2012, 8, 1, 22, 35, 0)
+ # DateTime.new(2012, 8, 29, 22, 35, 0).change(year: 1981, day: 1) # => DateTime.new(1981, 8, 1, 22, 35, 0)
+ # DateTime.new(2012, 8, 29, 22, 35, 0).change(year: 1981, hour: 0) # => DateTime.new(1981, 8, 29, 0, 0, 0)
def change(options)
::DateTime.civil(
options.fetch(:year, year),
@@ -70,63 +75,65 @@ def advance(options)
end
end
- # Returns a new DateTime representing the time a number of seconds ago
+ # Returns a new DateTime representing the time a number of seconds ago.
# Do not use this method in combination with x.months, use months_ago instead!
def ago(seconds)
since(-seconds)
end
- # Returns a new DateTime representing the time a number of seconds since the instance time
- # Do not use this method in combination with x.months, use months_since instead!
+ # Returns a new DateTime representing the time a number of seconds since the
+ # instance time. Do not use this method in combination with x.months, use
+ # months_since instead!
def since(seconds)
self + Rational(seconds.round, 86400)
end
alias :in :since
- # Returns a new DateTime representing the start of the day (0:00)
+ # Returns a new DateTime representing the start of the day (0:00).
def beginning_of_day
change(:hour => 0)
end
alias :midnight :beginning_of_day
alias :at_midnight :beginning_of_day
alias :at_beginning_of_day :beginning_of_day
- # Returns a new DateTime representing the end of the day (23:59:59)
+ # Returns a new DateTime representing the end of the day (23:59:59).
def end_of_day
change(:hour => 23, :min => 59, :sec => 59)
end
- # Returns a new DateTime representing the start of the hour (hh:00:00)
+ # Returns a new DateTime representing the start of the hour (hh:00:00).
def beginning_of_hour
change(:min => 0)
end
alias :at_beginning_of_hour :beginning_of_hour
- # Returns a new DateTime representing the end of the hour (hh:59:59)
+ # Returns a new DateTime representing the end of the hour (hh:59:59).
def end_of_hour
change(:min => 59, :sec => 59)
end
- # Adjusts DateTime to UTC by adding its offset value; offset is set to 0
+ # Adjusts DateTime to UTC by adding its offset value; offset is set to 0.
#
- # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)) # => Mon, 21 Feb 2005 10:11:12 -0600
- # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc # => Mon, 21 Feb 2005 16:11:12 +0000
+ # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)) # => Mon, 21 Feb 2005 10:11:12 -0600
+ # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc # => Mon, 21 Feb 2005 16:11:12 +0000
def utc
new_offset(0)
end
alias_method :getutc, :utc
- # Returns true if offset == 0
+ # Returns +true+ if <tt>offset == 0</tt>.
def utc?
offset == 0
end
- # Returns the offset value in seconds
+ # Returns the offset value in seconds.
def utc_offset
(offset * 86400).to_i
end
- # Layers additional behavior on DateTime#<=> so that Time and ActiveSupport::TimeWithZone instances can be compared with a DateTime
+ # Layers additional behavior on DateTime#<=> so that Time and
+ # ActiveSupport::TimeWithZone instances can be compared with a DateTime.
def <=>(other)
super other.to_datetime
end
@@ -53,7 +53,8 @@ def readable_inspect
alias_method :default_inspect, :inspect
alias_method :inspect, :readable_inspect
- # Returns DateTime with local offset for given year if format is local else offset is zero
+ # Returns DateTime with local offset for given year if format is local else
+ # offset is zero.
#
# DateTime.civil_from_format :local, 2012
# # => Sun, 01 Jan 2012 00:00:00 +0300
@@ -68,12 +69,12 @@ def self.civil_from_format(utc_or_local, year, month=1, day=1, hour=0, min=0, se
civil(year, month, day, hour, min, sec, offset)
end
- # Converts self to a floating-point number of seconds since the Unix epoch.
+ # Converts +self+ to a floating-point number of seconds since the Unix epoch.
def to_f
seconds_since_unix_epoch.to_f
end
- # Converts self to an integer number of seconds since the Unix epoch.
+ # Converts +self+ to an integer number of seconds since the Unix epoch.
def to_i
seconds_since_unix_epoch.to_i
end
@@ -6,13 +6,14 @@ class DateTime
# Time.zone = 'Hawaii' # => 'Hawaii'
# DateTime.new(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00
#
- # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone
- # instead of the operating system's time zone.
+ # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt>
+ # as the local zone instead of the operating system's time zone.
#
- # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument,
- # and the conversion will be based on that zone instead of <tt>Time.zone</tt>.
+ # You can also pass in a TimeZone instance or string that identifies a TimeZone
+ # as an argument, and the conversion will be based on that zone instead of
+ # <tt>Time.zone</tt>.
#
- # DateTime.new(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
+ # DateTime.new(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
def in_time_zone(zone = ::Time.zone)
if zone
ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.find_zone!(zone))
@@ -17,7 +17,6 @@ module Enumerable
# The default sum of an empty list is zero. You can override this default:
#
# [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0)
- #
def sum(identity = 0, &block)
if block_given?
map(&block).sum(identity)
@@ -32,7 +31,6 @@ def sum(identity = 0, &block)
# => { "nextangle" => <Person ...>, "chade-" => <Person ...>, ...}
# people.index_by { |person| "#{person.first_name} #{person.last_name}" }
# => { "Chade- Fowlersburg-e" => <Person ...>, "David Heinemeier Hansson" => <Person ...>, ...}
- #
def index_by
if block_given?
Hash[map { |elem| [yield(elem), elem] }]
@@ -41,8 +39,10 @@ def index_by
end
end
- # Returns true if the enumerable has more than 1 element. Functionally equivalent to enum.to_a.size > 1.
- # Can be called with a block too, much like any?, so <tt>people.many? { |p| p.age > 26 }</tt> returns true if more than one person is over 26.
+ # Returns +true+ if the enumerable has more than 1 element. Functionally
+ # equivalent to <tt>enum.to_a.size > 1</tt>. Can be called with a block too,
+ # much like any?, so <tt>people.many? { |p| p.age > 26 }</tt> returns +true+
+ # if more than one person is over 26.
def many?
cnt = 0
if block_given?
@@ -55,7 +55,8 @@ def many?
end
end
- # The negative of the <tt>Enumerable#include?</tt>. Returns true if the collection does not include the object.
+ # The negative of the <tt>Enumerable#include?</tt>. Returns +true+ if the
+ # collection does not include the object.
def exclude?(object)
!include?(object)
end
@@ -40,7 +40,7 @@ class Hash
# end
# end
#
- # {:foo => Foo.new}.to_xml(:skip_instruct => true)
+ # { foo: Foo.new }.to_xml(skip_instruct: true)
# # => "<hash><bar>fooing!</bar></hash>"
#
# * Otherwise, a node with +key+ as tag is created with a string representation of
@@ -1,8 +1,8 @@
class Hash
# Returns a new hash with +self+ and +other_hash+ merged recursively.
#
- # h1 = {x: {y: [4,5,6]}, z: [7,8,9]}
- # h2 = {x: {y: [7,8,9]}, z: "xyz"}
+ # h1 = { x: { y: [4,5,6] }, z: [7,8,9] }
+ # h2 = { x: { y: [7,8,9] }, z: 'xyz' }
#
# h1.deep_merge(h2) #=> {:x => {:y => [7, 8, 9]}, :z => "xyz"}
# h2.deep_merge(h1) #=> {:x => {:y => [4, 5, 6]}, :z => [7, 8, 9]}
@@ -3,7 +3,6 @@ class Hash
# limiting a set of parameters to everything but a few known toggles:
#
# @person.update_attributes(params[:person].except(:admin))
- #
def except(*keys)
dup.except!(*keys)
end
@@ -4,8 +4,7 @@ class Hash
# Returns an <tt>ActiveSupport::HashWithIndifferentAccess</tt> out of its receiver:
#
- # {:a => 1}.with_indifferent_access["a"] # => 1
- #
+ # { a: 1}.with_indifferent_access['a'] # => 1
def with_indifferent_access
ActiveSupport::HashWithIndifferentAccess.new_from_hash_copying_default(self)
end
@@ -17,8 +16,7 @@ def with_indifferent_access
# converting to an <tt>ActiveSupport::HashWithIndifferentAccess</tt> would not be
# desirable.
#
- # b = {:b => 1}
- # {:a => b}.with_indifferent_access["a"] # calls b.nested_under_indifferent_access
- #
+ # b = { b: 1 }
+ # { a: b }.with_indifferent_access['a'] # calls b.nested_under_indifferent_access
alias nested_under_indifferent_access with_indifferent_access
end
Oops, something went wrong.

0 comments on commit 794a70f

Please sign in to comment.