PR #2072 with docs

activesupport/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*    Adds Integer#ordinal to get the ordinal suffix string of an integer. *Tim Gildea*
+
 *    AS::Callbacks: `:per_key` option is no longer supported
 
 *    `AS::Callbacks#define_callbacks`: add `:skip_after_callbacks_if_terminated` option.

activesupport/lib/active_support/core_ext/integer/inflections.rb

@@ -14,4 +14,18 @@ class Integer
   def ordinalize
     ActiveSupport::Inflector.ordinalize(self)
   end
+
+  # Ordinal returns the suffix used to denote the position
+  # in an ordered sequence such as 1st, 2nd, 3rd, 4th.
+  #
+  #  1.ordinal     # => "st"
+  #  2.ordinal     # => "nd"
+  #  1002.ordinal  # => "nd"
+  #  1003.ordinal  # => "rd"
+  #  -11.ordinal   # => "th"
+  #  -1001.ordinal # => "st"
+  #
+  def ordinal
+    ActiveSupport::Inflector.ordinal(self)
+  end
 end

activesupport/lib/active_support/inflector/methods.rb

@@ -250,6 +250,29 @@ def safe_constantize(camel_cased_word)
       end
     end
 
+    # Returns the suffix that should be added to a number to denote the position
+    # in an ordered sequence such as 1st, 2nd, 3rd, 4th.
+    #
+    # Examples:
+    #   ordinal(1)     # => "st"
+    #   ordinal(2)     # => "nd"
+    #   ordinal(1002)  # => "nd"
+    #   ordinal(1003)  # => "rd"
+    #   ordinal(-11)   # => "th"
+    #   ordinal(-1021) # => "st"
+    def ordinal(number)
+      if (11..13).include?(number.to_i.abs % 100)
+        "th"
+      else
+        case number.to_i.abs % 10
+          when 1; "st"
+          when 2; "nd"
+          when 3; "rd"
+          else    "th"
+        end
+      end
+    end
+
     # Turns a number into an ordinal string used to denote the position in an
     # ordered sequence such as 1st, 2nd, 3rd, 4th.
     #
@@ -261,16 +284,7 @@ def safe_constantize(camel_cased_word)
     #   ordinalize(-11)   # => "-11th"
     #   ordinalize(-1021) # => "-1021st"
     def ordinalize(number)
-      if (11..13).include?(number.to_i.abs % 100)
-        "#{number}th"
-      else
-        case number.to_i.abs % 10
-          when 1; "#{number}st"
-          when 2; "#{number}nd"
-          when 3; "#{number}rd"
-          else    "#{number}th"
-        end
-      end
+      "#{number}#{ordinal(number)}"
     end
 
     private

activesupport/test/core_ext/integer_ext_test.rb

@@ -22,4 +22,9 @@ def test_ordinalize
     assert_equal '1st', 1.ordinalize
     assert_equal '8th', 8.ordinalize
   end
+
+  def test_ordinal
+    assert_equal 'st', 1.ordinal
+    assert_equal 'th', 8.ordinal
+  end
 end

activesupport/test/inflector_test.rb

@@ -303,6 +303,12 @@ def test_safe_constantize
   end
 
   def test_ordinal
+    OrdinalNumbers.each do |number, ordinalized|
+      assert_equal(ordinalized, number + ActiveSupport::Inflector.ordinal(number))
+    end
+  end
+
+  def test_ordinalize
     OrdinalNumbers.each do |number, ordinalized|
       assert_equal(ordinalized, ActiveSupport::Inflector.ordinalize(number))
     end

railties/guides/source/active_support_core_extensions.textile

@@ -1872,9 +1872,24 @@ The method +multiple_of?+ tests whether an integer is multiple of the argument:
 
 NOTE: Defined in +active_support/core_ext/integer/multiple.rb+.
 
+h4. +ordinal+
+
+The method +ordinal+ returns the ordinal suffix string corresponding to the receiver integer:
+
+<ruby>
+1.ordinal    # => "st"
+2.ordinal    # => "nd"
+53.ordinal   # => "rd"
+2009.ordinal # => "th"
+-21.ordinal  # => "st"
+-134.ordinal # => "th"
+</ruby>
+
+NOTE: Defined in +active_support/core_ext/integer/inflections.rb+.
+
 h4. +ordinalize+
 
-The method +ordinalize+ returns the ordinal string corresponding to the receiver integer:
+The method +ordinalize+ returns the ordinal string corresponding to the receiver integer. In comparison, note that the +ordinal+ method returns *only* the suffix string.
 
 <ruby>
 1.ordinalize    # => "1st"