diff options
Diffstat (limited to 'guides/source/active_support_core_extensions.textile')
| -rw-r--r-- | guides/source/active_support_core_extensions.textile | 135 |
1 files changed, 127 insertions, 8 deletions
diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile index afd43ab317..2addc50d68 100644 --- a/guides/source/active_support_core_extensions.textile +++ b/guides/source/active_support_core_extensions.textile @@ -84,7 +84,7 @@ The following values are considered to be blank in a Rails application: * any other object that responds to +empty?+ and it is empty. -INFO: In Ruby 1.9 the predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. In Ruby 1.8 whitespace is considered to be <tt>\s</tt> together with the ideographic space U+3000. +INFO: The predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank. @@ -1323,7 +1323,7 @@ Returns the character of the string at position +position+: "hello".at(0) # => "h" "hello".at(4) # => "o" "hello".at(-1) # => "o" -"hello".at(10) # => ERROR if < 1.9, nil in 1.9 +"hello".at(10) # => nil </ruby> NOTE: Defined in +active_support/core_ext/string/access.rb+. @@ -1805,7 +1805,7 @@ NOTE: Defined in +active_support/core_ext/numeric/bytes.rb+. h4. Time -Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years. +Enables the use of time calculations and declarations, like @45.minutes <plus> 2.hours <plus> 4.years@. These methods use Time#advance for precise date calculations when using from_now, ago, etc. as well as adding or subtracting their results from a Time object. For example: @@ -1840,6 +1840,76 @@ date and time arithmetic. NOTE: Defined in +active_support/core_ext/numeric/time.rb+. +h4. Formatting + +Enables the formatting of numbers in a variety of ways. + +Produce a string representation of a number as a telephone number: +<ruby> +5551234.to_s(:phone) # => 555-1234 +1235551234.to_s(:phone) # => 123-555-1234 +1235551234.to_s(:phone, :area_code => true) # => (123) 555-1234 +1235551234.to_s(:phone, :delimiter => " ") # => 123 555 1234 +1235551234.to_s(:phone, :area_code => true, :extension => 555) # => (123) 555-1234 x 555 +1235551234.to_s(:phone, :country_code => 1) # => +1-123-555-1234 +</ruby> + +Produce a string representation of a number as currency: +<ruby> +1234567890.50.to_s(:currency) # => $1,234,567,890.50 +1234567890.506.to_s(:currency) # => $1,234,567,890.51 +1234567890.506.to_s(:currency, :precision => 3) # => $1,234,567,890.506 +</ruby> + +Produce a string representation of a number as a percentage: +<ruby> +100.to_s(:percentage) # => 100.000% +100.to_s(:percentage, :precision => 0) # => 100% +1000.to_s(:percentage, :delimiter => '.', :separator => ',') # => 1.000,000% +302.24398923423.to_s(:percentage, :precision => 5) # => 302.24399% +</ruby> + +Produce a string representation of a number in delimited form: +<ruby> +12345678.to_s(:delimited) # => 12,345,678 +12345678.05.to_s(:delimited) # => 12,345,678.05 +12345678.to_s(:delimited, :delimiter => ".") # => 12.345.678 +12345678.to_s(:delimited, :delimiter => ",") # => 12,345,678 +12345678.05.to_s(:delimited, :separator => " ") # => 12,345,678 05 +</ruby> + +Produce a string representation of a number rounded to a precision: +<ruby> +111.2345.to_s(:rounded) # => 111.235 +111.2345.to_s(:rounded, :precision => 2) # => 111.23 +13.to_s(:rounded, :precision => 5) # => 13.00000 +389.32314.to_s(:rounded, :precision => 0) # => 389 +111.2345.to_s(:rounded, :significant => true) # => 111 +</ruby> + +Produce a string representation of a number as a human-readable number of bytes: +<ruby> +123.to_s(:human_size) # => 123 Bytes +1234.to_s(:human_size) # => 1.21 KB +12345.to_s(:human_size) # => 12.1 KB +1234567.to_s(:human_size) # => 1.18 MB +1234567890.to_s(:human_size) # => 1.15 GB +1234567890123.to_s(:human_size) # => 1.12 TB +</ruby> + +Produce a string representation of a number in human-readable words: +<ruby> +123.to_s(:human) # => "123" +1234.to_s(:human) # => "1.23 Thousand" +12345.to_s(:human) # => "12.3 Thousand" +1234567.to_s(:human) # => "1.23 Million" +1234567890.to_s(:human) # => "1.23 Billion" +1234567890123.to_s(:human) # => "1.23 Trillion" +1234567890123456.to_s(:human) # => "1.23 Quadrillion" +</ruby> + +NOTE: Defined in +active_support/core_ext/numeric/formatting.rb+. + h3. Extensions to +Integer+ h4. +multiple_of?+ @@ -2093,7 +2163,7 @@ h5. +to_formatted_s+ The method +to_formatted_s+ acts like +to_s+ by default. -If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs, though technically any object in Ruby 1.8 responds to +id+ indeed. Returned strings are: +If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs. Returned strings are: <ruby> [].to_formatted_s(:db) # => "null" @@ -2549,6 +2619,45 @@ There's also the bang variant +except!+ that removes keys in the very receiver. NOTE: Defined in +active_support/core_ext/hash/except.rb+. +h5. +transform_keys+ and +transform_keys!+ + +The method +transform_keys+ accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver: + +<ruby> +{nil => nil, 1 => 1, :a => :a}.transform_keys{ |key| key.to_s.upcase } +# => {"" => nil, "A" => :a, "1" => 1} +</ruby> + +The result in case of collision is undefined: + +<ruby> +{"a" => 1, :a => 2}.transform_keys{ |key| key.to_s.upcase } +# => {"A" => 2}, in my test, can't rely on this result though +</ruby> + +This method may be useful for example to build specialized conversions. For instance +stringify_keys+ and +symbolize_keys+ use +transform_keys+ to perform their key conversions: + +<ruby> +def stringify_keys + transform_keys{ |key| key.to_s } +end +... +def symbolize_keys + transform_keys{ |key| key.to_sym rescue key } +end +</ruby> + +There's also the bang variant +transform_keys!+ that applies the block operations to keys in the very receiver. + +Besides that, one can use +deep_transform_keys+ and +deep_transform_keys!+ to perform the block operation on all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_transform_keys{ |key| key.to_s.upcase } +# => {""=>nil, "1"=>1, "NESTED"=>{"A"=>3, "5"=>5}} +</ruby> + +NOTE: Defined in +active_support/core_ext/hash/keys.rb+. + h5. +stringify_keys+ and +stringify_keys!+ The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them: @@ -2579,6 +2688,13 @@ The second line can safely access the "type" key, and let the user to pass eithe There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver. +Besides that, one can use +deep_stringify_keys+ and +deep_stringify_keys!+ to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_stringify_keys +# => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}} +</ruby> + NOTE: Defined in +active_support/core_ext/hash/keys.rb+. h5. +symbolize_keys+ and +symbolize_keys!+ @@ -2613,6 +2729,13 @@ The second line can safely access the +:params+ key, and let the user to pass ei There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver. +Besides that, one can use +deep_symbolize_keys+ and +deep_symbolize_keys!+ to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, "nested" => {"a" => 3, 5 => 5}}.deep_symbolize_keys +# => {nil=>nil, 1=>1, :nested=>{:a=>3, 5=>5}} +</ruby> + NOTE: Defined in +active_support/core_ext/hash/keys.rb+. h5. +to_options+ and +to_options!+ @@ -2869,8 +2992,6 @@ d.prev_year # => Sun, 28 Feb 1999 d.next_year # => Wed, 28 Feb 2001 </ruby> -Active Support defines these methods as well for Ruby 1.8. - +prev_year+ is aliased to +last_year+. h6. +prev_month+, +next_month+ @@ -2892,8 +3013,6 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000 Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000 </ruby> -Active Support defines these methods as well for Ruby 1.8. - +prev_month+ is aliased to +last_month+. h6. +beginning_of_week+, +end_of_week+ |