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

Ticket #10124: as_array_docs.5.diff

File as_array_docs.5.diff, 6.8 kB (added by kampers, 7 months ago)

  • 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 a comma-separated 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" 
    1025        def to_sentence(options = {}) 
    1126          options.assert_valid_keys(:connector, :skip_last_comma) 
    1227          options.reverse_merge! :connector => 'and', :skip_last_comma => false 
    …… 
    2338              "#{self[0...-1].join(', ')}#{options[:skip_last_comma] ? '' : ','} #{options[:connector]}#{self[-1]}" 
    2439          end 
    2540        end 
    26  
    27         # When an array is given to url_for, it is converted to a slash separated string. 
     41         
     42        # Returns a slash-separated string from the array's elements. This 
     43        # method is used by +url_for+. 
     44        # 
     45        # ==== Examples 
     46        #   ["accounts", "new", 3].to_param 
     47        #   # => "accounts/new/3" 
     48        # 
     49        #   ["users", "opa2332", "pages", "personal"].to_param 
     50        #   # => "users/opa2332/pages/personal" 
    2851        def to_param 
    2952          join '/' 
    3053        end 
    3154 
    32         # Converts an array into a string suitable for use as a URL query string, using the given <tt>key</tt> as the 
    33         # param name. 
     55        # Returns a string from the array's elements suitable for use as a URL 
     56        # query string, using the given +key+ as the param name. 
    3457        # 
    35         # ==== Example: 
     58        # ==== Example 
    3659        #   ['Rails', 'coding'].to_query('hobbies') => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding" 
    3760        def to_query(key) 
    3861          collect { |value| value.to_query("#{key}[]") } * '&' 
    …… 
    4568          end 
    4669        end 
    4770 
     71        # Returns a string from the array's elements. The string's composition 
     72        # is determined by the +format+ parameter: 
     73        # * <tt>:db</tt> - a comma-separated list of each element's response to 
     74        #   calling +id+, or <tt>"null"</tt> if the array is empty 
     75        # * Otherwise, Ruby's default +to_s+ behavior is used. 
     76        # 
     77        # This method is also aliased as +to_s+. 
     78        # 
     79        # ==== Examples 
     80        #   ["Robert", "Kevin", "Ryan"].to_formatted_s    # => "RobertKevinRyan" 
     81        #      
     82        #   david  = Person.find(1) 
     83        #   robert = Person.find(5) 
     84        #   [david, robert].to_formatted_s(:db)           # => "1,5" 
    4885        def to_formatted_s(format = :default) 
    4986          case format 
    5087            when :db 
    …… 
    5794              to_default_s 
    5895          end 
    5996        end 
    60  
     97               
     98        # Attempts to return a string of XML from the array's elements. Each 
     99        # element must respond to +to_xml+, or an error will be raised. 
     100        # 
     101        # ==== Options 
     102        # * <tt>:root</tt> - The name of the root element (default: the 
     103        #   pluralized class name of the elements if they are homogeneous, or 
     104        #   <tt>"records"</tt> otherwise) 
     105        # * <tt>:children</tt> - The name of the child elements (default: the 
     106        #   singular version of the root element's name) 
     107        # * <tt>:indent</tt> - Number of spaces to indent the XML (default: 
     108        #   <tt>2</tt>) 
     109        # * <tt>:builder</tt> - The Builder instance to use to generate the XML 
     110        #   (default: a new instance of <tt>Builder::XmlMarkup</tt>) 
     111        # * <tt>:dasherize</tt> - Whether to use dashes instead of underscores 
     112        #   when formatting the root element's name (default: +true+) 
     113        # * <tt>:skip_instruct</tt> - Whether to omit the XML declaration from 
     114        #   the beginning of the string (default: +false+) 
     115        # * <tt>:skip_types</tt> - Whether to omit the +type+ attributes from 
     116        #   the XML tags, such as <tt>type="array"</tt> (default: +false+) 
     117        # 
     118        # If a block is given, it will be called with the Builder instance so 
     119        # that you can insert arbitrary XML or adjust Builder options before the 
     120        # array elements are processed. 
     121        # 
     122        # ==== Examples 
     123        # 
     124        #   [1, 2, 3].to_xml 
     125        #   # => RuntimeError: Not all elements respond to to_xml 
     126        #  
     127        #   [{'key' => 'value', 'key2' => 'value'}, {'name' => 'Ruby on Rails'}].to_xml 
     128        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     129        #         <records type="array"> 
     130        #           <record> 
     131        #             <key2>value</key2> 
     132        #             <key>value</key> 
     133        #           </record> 
     134        #           <record> 
     135        #             <name>Ruby on Rails</name> 
     136        #           </record> 
     137        #         </records>' 
     138        # 
     139        #   [{'color' => 'orange'}].to_xml(:root => 'vegetables', :children => 'carrot') 
     140        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     141        #         <vegetables type="array"> 
     142        #           <carrot> 
     143        #             <color>orange</color> 
     144        #           </carrot> 
     145        #         </beets>' 
     146        # 
     147        #   [{'height' => 1.8}].to_xml(:root => 'people') { |xml| 
     148        #     xml.comment!('All measurements are in meters.') 
     149        #   } 
     150        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     151        #         <people type="array"> 
     152        #           <!-- All measurements are in meters. --> 
     153        #           <person> 
     154        #             <height type="float">1.8</height> 
     155        #           </person> 
     156        #         </people>' 
    61157        def to_xml(options = {}) 
    62158          raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml } 
    63159