From 158473f0d113f0c0b02ba9b7353c10949172a1f7 Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Wed, 2 Jun 2010 00:28:23 +0200
Subject: AS guide: documents String#truncate

---
 .../source/active_support_core_extensions.textile  | 33 ++++++++++++++++++++++
 1 file changed, 33 insertions(+)

(limited to 'railties/guides/source/active_support_core_extensions.textile')

diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 08fddd2926..de82e871a6 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/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:
-- 
cgit v1.2.3

