AS guide: documents String#(start|end)_with?

1 files changed, 25 insertions, 0 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index 06d750afc9..392e9388df 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -704,6 +704,31 @@ In Ruby 1.9 the <tt>%</tt> string operator supports key-based interpolation, bot
 
 Active Support adds that functionality to <tt>%</tt> in previous versions of Ruby.
 
+h4. +start_with?+ and +end_width?+
+
+Ruby 1.8.7 and up define the predicates +String#start_with?+ and +String#end_with?+:
+
+<ruby>
+"foo".start_with?("f") # => true
+"foo".start_with?("g") # => false
+"foo".start_with?("")  # => true
+
+"foo".end_with?("o")   # => true
+"foo".end_with?("p")   # => false
+"foo".end_with?("")    # => true
+</ruby>
+
+If strings do not respond to those methods Active Support emulates them, and also defines their 3rd person aliases:
+
+<ruby>
+"foo".starts_with?("f") # => true
+"foo".ends_with?("o")   # => true
+</ruby>
+
+in case you feel more confortable spelling them that way.
+
+WARNING. Active Support invokes +to_s+ on the argument, but Ruby does not. Since Active Support defines these methods only if strings do not respond to them, this corner of their behaviour depends on the interpreter that runs a given Rails application. You change the interpreter, and +start_with?(1)+ may change its return value. In consequence, it's more portable not to rely on that and pass always strings.
+
 
 h3. Extensions to +Numeric+