diff options
Diffstat (limited to 'guides/source/active_support_core_extensions.md')
| -rw-r--r-- | guides/source/active_support_core_extensions.md | 36 |
1 files changed, 19 insertions, 17 deletions
diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 4b2cc947b5..401e6f0596 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -14,7 +14,7 @@ How to Load Core Extensions ### Stand-Alone Active Support -In order to have a near zero default footprint, Active Support does not load anything by default. It is broken in small pieces so that you may load just what you need, and also has some convenience entry points to load related extensions in one shot, even everything. +In order to have a near-zero default footprint, Active Support does not load anything by default. It is broken in small pieces so that you can load just what you need, and also has some convenience entry points to load related extensions in one shot, even everything. Thus, after a simple require like: @@ -85,11 +85,11 @@ The following values are considered to be blank in a Rails application: * empty arrays and hashes, and -* any other object that responds to `empty?` and it is empty. +* any other object that responds to `empty?` and is empty. INFO: The predicate for strings uses the Unicode-aware character class `[:space:]`, 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. +WARNING: Note that numbers are not mentioned. In particular, 0 and 0.0 are **not** blank. For example, this method from `ActionDispatch::Session::AbstractStore` uses `blank?` for checking whether a session key is present: @@ -147,19 +147,21 @@ Some numbers which are not singletons are not duplicable either: Active Support provides `duplicable?` to programmatically query an object about this property: ```ruby +"foo".duplicable? # => true "".duplicable? # => true +0.0.duplicable? # => false false.duplicable? # => false ``` -By definition all objects are `duplicable?` except `nil`, `false`, `true`, symbols, numbers, and class and module objects. +By definition all objects are `duplicable?` except `nil`, `false`, `true`, symbols, numbers, class, and module objects. -WARNING. Any class can disallow duplication removing `dup` and `clone` or raising exceptions from them, only `rescue` can tell whether a given arbitrary object is duplicable. `duplicable?` depends on the hard-coded list above, but it is much faster than `rescue`. Use it only if you know the hard-coded list is enough in your use case. +WARNING: Any class can disallow duplication by removing `dup` and `clone` or raising exceptions from them. Thus only `rescue` can tell whether a given arbitrary object is duplicable. `duplicable?` depends on the hard-coded list above, but it is much faster than `rescue`. Use it only if you know the hard-coded list is enough in your use case. NOTE: Defined in `active_support/core_ext/object/duplicable.rb`. ### `deep_dup` -The `deep_dup` method returns deep copy of a given object. Normally, when you `dup` an object that contains other objects, ruby does not `dup` them. If you have an array with a string, for example, it will look like this: +The `deep_dup` method returns deep copy of a given object. Normally, when you `dup` an object that contains other objects, ruby does not `dup` them, so it creates a shallow copy of the object. If you have an array with a string, for example, it will look like this: ```ruby array = ['string'] @@ -167,18 +169,18 @@ duplicate = array.dup duplicate.push 'another-string' -# object was duplicated, so element was added only to duplicate +# the object was duplicated, so the element was added only to the duplicate array #=> ['string'] duplicate #=> ['string', 'another-string'] duplicate.first.gsub!('string', 'foo') -# first element was not duplicated, it will be changed for both arrays +# first element was not duplicated, it will be changed in both arrays array #=> ['foo'] duplicate #=> ['foo', 'another-string'] ``` -As you can see, after duplicating `Array` instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since `dup` does not make deep copy, the string inside array is still the same object. +As you can see, after duplicating the `Array` instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since `dup` does not make deep copy, the string inside the array is still the same object. If you need a deep copy of an object, you should use `deep_dup`. Here is an example: @@ -192,12 +194,12 @@ array #=> ['string'] duplicate #=> ['foo'] ``` -If object is not duplicable, `deep_dup` will just return this object: +If the object is not duplicable, `deep_dup` will just return it: ```ruby number = 1 -dup = number.deep_dup -number.object_id == dup.object_id # => true +duplicate = number.deep_dup +number.object_id == duplicate.object_id # => true ``` NOTE: Defined in `active_support/core_ext/object/deep_dup.rb`. @@ -1913,8 +1915,8 @@ Produce a string representation of a number as a telephone number: 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.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 ``` @@ -1934,8 +1936,8 @@ Produce a string representation of a number as a percentage: 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) # => 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 @@ -1944,7 +1946,7 @@ Produce a string representation of a number in delimited form: Produce a string representation of a number rounded to a precision: ```ruby -111.2345.to_s(:rounded) # => 111.235 +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 |