From 0ce7840b9b9a858196b70680affffdc03f8058af Mon Sep 17 00:00:00 2001 From: "Michael D.W. Prendergast" Date: Mon, 22 Dec 2014 22:28:45 -0500 Subject: Update Active Record's attribute query methods documentation to describe its full behaviour. [ci skip] --- activerecord/lib/active_record/base.rb | 38 ++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index f978fbd0a4..a96da388dc 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -140,8 +140,7 @@ module ActiveRecord #:nodoc: # == Attribute query methods # # In addition to the basic accessors, query methods are also automatically available on the Active Record object. - # Query methods allow you to test whether an attribute value is present. - # For numeric values, present is defined as non-zero. + # A query method returns true or false depending on the value of the attribute. # # For example, an Active Record User with the name attribute has a name? method that you can call # to determine whether the user has a name: @@ -152,6 +151,41 @@ module ActiveRecord #:nodoc: # anonymous = User.new(name: "") # anonymous.name? # => false # + # When an attribute's value is nil, the query method will return false: + # + # user = User.new(name: nil) + # user.name? # => false + # + # When the value is not nil, whether true or false is returned depends on the + # attribute's underlying class. + # + # When used on a boolean attribute, the query method returns false if the + # attribute is false, or true if it is true: + # + # user = User.new(has_joined_newsletter: false) + # user.has_joined_newsletter? # => false + # + # user.has_joined_newsletter = true + # user.has_joined_newsletter? # => true + # + # In other words, it returns the value of the boolean attribute. + # + # For numeric attributes, the query method will return false if the value is + # zero, or true otherwise: + # + # user = User.new(age: 0) + # user.age? # => false + # + # user.age = 25 + # user.age? # => true + # + # With other classes, the query method returns true if the value is present + # (more specifically, it returns true if it is not blank, as defined by + # Object#blank?). For instance, as seen above, a non-blank String + # would cause the query method to return true, while a blank String would + # return false. A String is considered blank when it has a length of zero, + # or contains only whitespace. + # # == Accessing attributes before they have been typecasted # # Sometimes you want to be able to read the raw attribute data without having the column-determined -- cgit v1.2.3 From e35432689e43ffb833a39a2c3dde28e11fabaa8e Mon Sep 17 00:00:00 2001 From: "Michael D.W. Prendergast" Date: Tue, 23 Dec 2014 01:54:40 -0500 Subject: Clarify that the word present refers to Object#present?. [ci skip] Update Active Record's attribute query methods documentation to clarify that whether an attribute is present is based on Object#present?. This gives people a place to go see what the exact definition of presence is. [ci skip] --- activerecord/lib/active_record/base.rb | 38 ++-------------------------------- 1 file changed, 2 insertions(+), 36 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index a96da388dc..08322921c6 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -140,7 +140,8 @@ module ActiveRecord #:nodoc: # == Attribute query methods # # In addition to the basic accessors, query methods are also automatically available on the Active Record object. - # A query method returns true or false depending on the value of the attribute. + # Query methods allow you to test whether an attribute value is present, as defined by Object#present?. + # For numeric values, present is defined as non-zero. # # For example, an Active Record User with the name attribute has a name? method that you can call # to determine whether the user has a name: @@ -151,41 +152,6 @@ module ActiveRecord #:nodoc: # anonymous = User.new(name: "") # anonymous.name? # => false # - # When an attribute's value is nil, the query method will return false: - # - # user = User.new(name: nil) - # user.name? # => false - # - # When the value is not nil, whether true or false is returned depends on the - # attribute's underlying class. - # - # When used on a boolean attribute, the query method returns false if the - # attribute is false, or true if it is true: - # - # user = User.new(has_joined_newsletter: false) - # user.has_joined_newsletter? # => false - # - # user.has_joined_newsletter = true - # user.has_joined_newsletter? # => true - # - # In other words, it returns the value of the boolean attribute. - # - # For numeric attributes, the query method will return false if the value is - # zero, or true otherwise: - # - # user = User.new(age: 0) - # user.age? # => false - # - # user.age = 25 - # user.age? # => true - # - # With other classes, the query method returns true if the value is present - # (more specifically, it returns true if it is not blank, as defined by - # Object#blank?). For instance, as seen above, a non-blank String - # would cause the query method to return true, while a blank String would - # return false. A String is considered blank when it has a length of zero, - # or contains only whitespace. - # # == Accessing attributes before they have been typecasted # # Sometimes you want to be able to read the raw attribute data without having the column-determined -- cgit v1.2.3 From c9d86d4148783df4885a9fa4f623fdf6c3079282 Mon Sep 17 00:00:00 2001 From: "Michael D.W. Prendergast" Date: Tue, 23 Dec 2014 19:32:49 -0500 Subject: Clarify that query methods have a custom definition of whether a numeric value is present. [ci skip] The way Active Record query methods handle numeric values is a special case, and is not part of Rails's standard definition of present. This update attempts to make this more clear in the docs, so that people don't expect Object#present? to return false if used on a number that is zero. --- activerecord/lib/active_record/base.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'activerecord/lib') diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 08322921c6..954d22f1d5 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -140,8 +140,8 @@ module ActiveRecord #:nodoc: # == Attribute query methods # # In addition to the basic accessors, query methods are also automatically available on the Active Record object. - # Query methods allow you to test whether an attribute value is present, as defined by Object#present?. - # For numeric values, present is defined as non-zero. + # Query methods allow you to test whether an attribute value is present. + # Additionally, when dealing with numeric values, a query method will return false if the value is zero. # # For example, an Active Record User with the name attribute has a name? method that you can call # to determine whether the user has a name: -- cgit v1.2.3