Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #10124: as_array_docs.4.diff

File as_array_docs.4.diff, 6.4 kB (added by revans, 8 months ago)

  • vendor/rails/activesupport/lib/active_support/core_ext/array/conversions.rb

    old new  
    44  module CoreExtensions #:nodoc: 
    55    module Array #:nodoc: 
    66      module Conversions 
    7         # Converts the array to comma-seperated sentence where the last element is joined by the connector word. Options: 
    8         # * <tt>:connector</tt> - The word used to join the last element in arrays with two or more elements (default: "and") 
    9         # * <tt>:skip_last_comma</tt> - Set to true to return "a, b and c" instead of "a, b, and c". 
     7        # Returns a comma-seperated string in which the last element of the 
     8        # array is joined by a connector word. 
     9        # 
     10        # ==== Options 
     11        # * <tt>:connector</tt> - The string used to join the last element in 
     12        #   arrays with two or more elements (default: <tt>"and"</tt>) 
     13        # * <tt>:skip_last_comma</tt> - Set to +true+ to return 
     14        #   <tt>"a, b and c"</tt> instead of <tt>"a, b, and c"</tt> 
     15        # 
     16        # ==== Examples 
     17        #   ["Lions", "tigers", "bears"].to_sentence 
     18        #   # => "Lions, tigers, and bears" 
     19        # 
     20        #   ["Active Record", "Action Pack", "Active Resource"].to_sentence(:connector => "or") 
     21        #   # => "Active Record, Action Pack, or Active Resource"  
     22        # 
     23        #   ["red", "green", "blue"].to_sentence(:skip_last_comma => true) 
     24        #   # => "red, green and blue" 
     25        # 
    1026        def to_sentence(options = {}) 
    1127          options.assert_valid_keys(:connector, :skip_last_comma) 
    1228          options.reverse_merge! :connector => 'and', :skip_last_comma => false 
    …… 
    2541        end 
    2642 
    2743        # When an array is given to url_for, it is converted to a slash separated string. 
     44        # Returns a slash-separated string from the array's elements. This 
     45        # method is used by +url_for+. 
     46        # 
     47        # ==== Examples 
     48        #   ["accounts", "new", 3].to_param 
     49        #   # => "accounts/new/3" 
     50        # 
     51        #   ["users", "opa2332", "pages", "personal"].to_param 
     52        #   # => "users/opa2332/pages/personal" 
     53        # 
    2854        def to_param 
    2955          join '/' 
    3056        end 
    31  
     57         
    3258        def self.included(base) #:nodoc: 
    3359          base.class_eval do 
    3460            alias_method :to_default_s, :to_s 
    …… 
    3662          end 
    3763        end 
    3864 
     65        # Converts an Array to a formatted string 
     66        #  
     67        # This method is also aliased as <tt>to_s</tt>. 
     68        # 
     69        # 
     70        # == Options: 
     71        # * <tt>:db</tt> - Will return a string of the given objects id's. 
     72        # * <tt>:default</tt> - Is the default behavious that will take the given objects and return them 
     73        #   as 1 string. 
     74        # 
     75        # === Examples: 
     76        # 
     77        #   ["Robert", "Kevin", "Ryan"].to_formatted_s    # => "RobertKevinRyan" 
     78        #      
     79        #   david  = Person.find(1)                       # => david.id == 1 
     80        #   robert = Person.find(5)                       # => robert.id == 5 
     81        #    
     82        #   [david, robert].to_formatted_s(:db)           # => "1,5" 
     83        # 
    3984        def to_formatted_s(format = :default) 
    4085          case format 
    4186            when :db 
    …… 
    4893              to_default_s 
    4994          end 
    5095        end 
    51  
     96         
     97        # Attempts to return a string of XML from the array's elements. Each 
     98        # element must respond to +to_xml+, or an error will be raised. 
     99        # 
     100        # ==== Options 
     101        # * <tt>:root</tt> - The name of the root element (default: the 
     102        #   pluralized class name of the elements if they are homogeneous, or 
     103        #   <tt>"records"</tt> otherwise) 
     104        # * <tt>:children</tt> - The name of the child elements (default: the 
     105        #   singular version of the root element's name) 
     106        # * <tt>:indent</tt> - Number of spaces to indent the XML (default: 
     107        #   <tt>2</tt>) 
     108        # * <tt>:builder</tt> - The Builder instance to use to generate the XML 
     109        #   (default: a new instance of <tt>Builder::XmlMarkup</tt>) 
     110        # * <tt>:dasherize</tt> - Whether to use dashes instead of underscores 
     111        #   when formatting the root element's name (default: +true+) 
     112        # * <tt>:skip_instruct</tt> - Whether to omit the XML declaration from 
     113        #   the beginning of the string (default: +false+) 
     114        # * <tt>:skip_types</tt> - Whether to omit the +type+ attributes from 
     115        #   the XML tags, such as <tt>type="array"</tt> (default: +false+) 
     116        # 
     117        # If a block is given, it will be called with the Builder instance so 
     118        # that you can insert arbitrary XML or adjust Builder options before the 
     119        # array elements are processed. 
     120        # 
     121        # ==== Examples 
     122        # 
     123        #   [1, 2, 3].to_xml 
     124        #   # => RuntimeError: Not all elements respond to to_xml 
     125        #  
     126        #   [{'key' => 'value', 'key2' => 'value'}, {'name' => 'Ruby on Rails'}].to_xml 
     127        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     128        #         <records type="array"> 
     129        #           <record> 
     130        #             <key2>value</key2> 
     131        #             <key>value</key> 
     132        #           </record> 
     133        #           <record> 
     134        #             <name>Ruby on Rails</name> 
     135        #           </record> 
     136        #         </records>' 
     137        # 
     138        #   [{'color' => 'orange'}].to_xml(:root => 'vegetables', :children => 'carrot') 
     139        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     140        #         <vegetables type="array"> 
     141        #           <carrot> 
     142        #             <color>orange</color> 
     143        #           </carrot> 
     144        #         </beets>' 
     145        # 
     146        #   [{'height' => 1.8}].to_xml(:root => 'people') { |xml| 
     147        #     xml.comment!('All measurements are in meters.') 
     148        #   } 
     149        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     150        #         <people type="array"> 
     151        #           <!-- All measurements are in meters. --> 
     152        #           <person> 
     153        #             <height type="float">1.8</height> 
     154        #           </person> 
     155        #         </people>' 
     156        # 
    52157        def to_xml(options = {}) 
    53158          raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml } 
    54159