1 files changed, 19 insertions, 0 deletions

diff --git a/doc/string/grapheme_clusters.rdoc b/doc/string/grapheme_clusters.rdoc
new file mode 100644
index 0000000000..ee8b45700e
--- /dev/null
+++ b/doc/string/grapheme_clusters.rdoc
@@ -0,0 +1,19 @@
+Returns an array of the grapheme clusters in +self+
+(see {Unicode Grapheme Cluster Boundaries}[https://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries]):
+
+  s = "ä-pqr-b̈-xyz-c̈"
+  s.size                   # => 16
+  s.bytesize               # => 19
+  s.grapheme_clusters.size # => 13
+  s.grapheme_clusters
+  # => ["ä", "-", "p", "q", "r", "-", "b̈", "-", "x", "y", "z", "-", "c̈"]
+
+Details:
+
+  s = "ä"
+  s.grapheme_clusters             # => ["ä"]           # One grapheme cluster.
+  s.bytes                         # => [97, 204, 136]  # Three bytes.
+  s.chars                         # => ["a", "̈"]       # Two characters.
+  s.chars.map {|char| char.ord }  # => [97, 776]       # Their values.
+
+Related: see {Converting to Non-String}[rdoc-ref:String@Converting+to+Non-String].