drbrain	2013-01-17 07:50:54 +0900 (Thu, 17 Jan 2013)

  New Revision: 38852

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38852

  Log:
    * doc/syntax/control_expressions.rdoc (Flip-Flop):  Added a section on
      the flip-flop.

  Modified files:
    trunk/ChangeLog
    trunk/doc/syntax/control_expressions.rdoc

Index: doc/syntax/control_expressions.rdoc
===================================================================
--- doc/syntax/control_expressions.rdoc	(revision 38851)
+++ doc/syntax/control_expressions.rdoc	(revision 38852)
@@ -418,3 +418,62 @@ longer true, now you will receive a Synt https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L418
 of a +rescue+ block.  See {Exceptions}[rdoc-ref:syntax/exceptions.rdoc]
 for proper usage of +retry+.
 
+== Flip-Flop
+
+The flip-flop is rarely seen conditional expression.  It's primary use is
+for processing text from ruby one-line programs used with <code>ruby -n</code>
+or <code>ruby -p</code>.
+
+The form of the flip-flop is an expression that indicates when the
+flip-flop turns on, <code>..</code> (or <code>...</code>), then an expression
+that indicates when the flip-flop will turn off.  While the flip-flop is on it
+will continue to evaluate to +true+, and +false+ when off.
+
+Here is an example:
+
+
+  selected = []
+
+  0.upto 10 do |value|
+    selected << value if value==2..value==8
+  end
+
+  p selected # prints [2, 3, 4, 5, 6, 7, 8]
+
+In the above example the on condition is <code>n==2</code>.  The flip-flop
+is initially off (false) for 0 and 1, but becomes on (true) for 2 and remains
+on through 8.  After 8 it turns off and remains off for 9 and 10.
+
+The flip-flop must be used inside a conditional such as +if+, +while+,
++unless+, +until+ etc. including the modifier forms.
+
+When you use an inclusive range (<code>..</code>) the off condition is
+evaluated when the on condition changes:
+
+  selected = []
+
+  0.upto 5 do |value|
+    selected << value if value==2..value==2
+  end
+
+  p selected # prints [2]
+
+Here both sides of the flip-flop are evaluated so the flip-flop turns on and
+off only when +value+ equals 2.  Since the flip-flop turned on in the
+iteration it returns true.
+
+When you use an exclusive range (<code>...</code>) the off condition is
+evaluated on the following iteration:
+
+  selected = []
+
+  0.upto 5 do |value|
+    selected << value if value==2...value==2
+  end
+
+  p selected # prints [2, 3, 4, 5]
+
+Here the flip-flop turns on when +value+ equals 2 but doesn't turn off on the
+same iteration.  The off condition isn't evaluated until the following
+iteration and +value+ will never be two again.
+
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 38851)
+++ ChangeLog	(revision 38852)
@@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Thu Jan 17 07:50:26 2013  Eric Hodel  <drbrain@s...>
+
+	* doc/syntax/control_expressions.rdoc (Flip-Flop):  Added a section on
+	  the flip-flop.
+
 Thu Jan 17 06:59:51 2013  Eric Hodel  <drbrain@s...>
 
 	* doc/syntax/control_expressions.rdoc (if Expressions):  Fixed markup

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/