Browse files

AS guide: documents String#truncate

  • Loading branch information...
1 parent 82f6758 commit 158473f0d113f0c0b02ba9b7353c10949172a1f7 @fxn fxn committed Jun 2, 2010
Showing with 33 additions and 0 deletions.
  1. +33 −0 railties/guides/source/active_support_core_extensions.textile
View
33 railties/guides/source/active_support_core_extensions.textile
@@ -1254,6 +1254,39 @@ There's also the destructive version +String#squish!+.
NOTE: Defined in +active_support/core_ext/string/filters.rb+.
+h4. +truncate+
+
+The method +truncate+ returns a copy of its receiver truncated after a given +length+:
+
+<ruby>
+"Oh dear! Oh dear! I shall be late!".truncate(20)
+# => "Oh dear! Oh dear!..."
+</ruby>
+
+Ellipsis can be customized with the +:omission+ option:
+
+<ruby>
+"Oh dear! Oh dear! I shall be late!".truncate(20, :omission => '&hellip;')
+# => "Oh dear! Oh &hellip;"
+</ruby>
+
+Note in particular that truncation takes into account the length of the omission string.
+
+Pass a +:separator+ to truncate the string at a natural break:
+
+<ruby>
+"Oh dear! Oh dear! I shall be late!".truncate(18)
+# => "Oh dear! Oh dea..."
+"Oh dear! Oh dear! I shall be late!".truncate(18, :separator => ' ')
+# => "Oh dear! Oh..."
+</ruby>
+
+In the above example "dear" gets cut first, but then +:separator+ prevents it.
+
+WARNING: The option +:separator+ can't be a regexp.
+
+NOTE: Defined in +active_support/core_ext/string/filters.rb+.
+
h4. Key-based Interpolation
In Ruby 1.9 the <tt>%</tt> string operator supports key-based interpolation, both formatted and unformatted:

0 comments on commit 158473f

Please sign in to comment.