reviewer patch: improved function operator; extended and rewrote docs…

…trings

- operator can is now not limited to binary operators anymore
- rewrote docstring of operator, add, sub, abs
- added additional examples (more a note...)

src/sage/combinat/finite_state_machine_generators.py

@@ -88,6 +88,7 @@ def CountSubblockOccurrences(self, block, input_alphabet):
         INPUT:
 
         - ``block`` -- a list (or other iterable) of letters.
+
         - ``input_alphabet`` -- input alphabet.
 
         OUTPUT:
@@ -187,26 +188,35 @@ def transition_function(read, input):
             s.is_final = True
         return T
 
-    def operator(self, operator, input_alphabet):
+
+    def operator(self, operator, input_alphabet, number_of_operands=2):
         r"""
-        Returns a transducer which realizes the binary operator over
-        an input alphabet.
+        Returns a transducer which realizes a letter-wise
+        operation of an input word over the given input alphabet.
 
         INPUT:
 
-        - ``operator`` -- binary operator to realize (a map defined on
-          ``input_alphabet`` `\times` ``input_alphabet``).
-        - ``input_alphabet``  -- input alphabet.
+        - ``operator`` -- operator to realize. It is a function which
+          takes ``number_of_operands`` input arguments (each out of
+          ``input_alphabet``).
+
+        - ``input_alphabet``  -- a list or other iterable.
+
+        - ``number_of_operands`` -- (default: `2`) it specifies the number
+          of input arguments the operator takes.
 
         OUTPUT:
 
-        A transducer mapping `(i_0, i'_0)\ldots (i_k, i'_k)`
-        to `(i_0\odot i'_0)\ldots (i_k \odot i'_k)` where
-        `\odot` stands for the operator given.
+        A transducer mapping an input letter `(i_1, \dots, i_n)` to
+        `\mathrm{operator}(i_1, \dots, i_n)`. Here, `n` equals
+        ``number_of_operands``.
+
+        The input alphabet of the generated transducer is the cartesian
+        product of ``number_of_operands`` copies of ``input_alphabet``.
 
         EXAMPLE:
 
-        The following transducer realizes component-wise
+        The following binary transducer realizes component-wise
         addition::
 
             sage: import operator
@@ -225,34 +235,51 @@ def operator(self, operator, input_alphabet):
             [0]
             sage: T([(0, 0), (0, 1), (1, 0), (1, 1)])
             [0, 1, 1, 2]
+
+        Note that for a unary operator the input letters of the
+        new transducer are tuples of length `1`::
+
+            sage: T = transducers.operator(lambda i: abs(i),
+            ....:                          [-1, 0, 1],
+            ....:                          number_of_operands=1)
+            sage: T([-1, 1, 0])
+            Traceback (most recent call last):
+            ...
+            ValueError: Invalid input sequence.
+            sage: T([(-1,), (1,), (0,)])
+            [1, 1, 0]
         """
         from itertools import product
 
-        def transition_function(state, (i, o)):
-            return(0, operator(i, o))
-        pairs = list(product(input_alphabet, repeat=2))
+        def transition_function(state, operands):
+            return (0, operator(*operands))
+        pairs = list(product(input_alphabet, repeat=number_of_operands))
         return Transducer(transition_function,
                           input_alphabet=pairs,
                           initial_states=[0],
                           final_states=[0])
 
+
     def add(self, input_alphabet):
         """
-        Returns a transducer which realizes the component-wise
-        addition over an input alphabet.
+        Returns a transducer which realizes the letter-wise
+        addition of an input word over the given input alphabet.
 
         INPUT:
 
-        - ``input_alphabet``  -- input alphabet.
+        - ``input_alphabet``  -- a list or other iterable.
 
         OUTPUT:
 
-        A transducer mapping `(i_0, i'_0)\ldots (i_k, i'_k)`
-        to `(i_0 + i'_0)\ldots (i_k + i'_k)`.
+        A transducer mapping an input word `(i_0, i'_0)\ldots (i_k, i'_k)`
+        to the word `(i_0 + i'_0)\ldots (i_k + i'_k)`.
+
+        The input alphabet of the generated transducer is the cartesian
+        product of two copies of ``input_alphabet``.
 
         EXAMPLE:
 
-        The following transducer realizes component-wise
+        The following transducer realizes letter-wise
         addition::
 
             sage: T = transducers.add([0, 1])
@@ -273,23 +300,27 @@ def add(self, input_alphabet):
         import operator
         return self.operator(operator.add, input_alphabet)
 
+
     def sub(self, input_alphabet):
         """
-        Returns a transducer which realizes the component-wise
-        addition over an input alphabet.
+        Returns a transducer which realizes the letter-wise
+        subtraction of an input word over the given input alphabet.
 
         INPUT:
 
-        - ``input_alphabet``  -- input alphabet.
+        - ``input_alphabet``  -- a list or other iterable.
 
         OUTPUT:
 
-        A transducer mapping `(i_0, i'_0)\ldots (i_k, i'_k)`
-        to `(i_0 - i'_0)\ldots (i_k - i'_k)`.
+        A transducer mapping an input word `(i_0, i'_0)\ldots (i_k, i'_k)`
+        to the word `(i_0 - i'_0)\ldots (i_k - i'_k)`.
+
+        The input alphabet of the generated transducer is the cartesian
+        product of two copies of ``input_alphabet``.
 
         EXAMPLE:
 
-        The following transducer realizes component-wise
+        The following transducer realizes letter-wise
         subtraction::
 
             sage: T = transducers.sub([0, 1])
@@ -313,12 +344,12 @@ def sub(self, input_alphabet):
 
     def abs(self, input_alphabet):
         """
-        Returns a transducer which realizes the component-wise
-        absolute value over an input alphabet.
+        Returns a transducer which realizes the letter-wise
+        absolute value of an input word over the given input alphabet.
 
         INPUT:
 
-        - ``input_alphabet``  -- input alphabet.
+        - ``input_alphabet``  -- a list or other iterable.
 
         OUTPUT:
 
@@ -327,7 +358,7 @@ def abs(self, input_alphabet):
 
         EXAMPLE:
 
-        The following transducer realizes component-wise
+        The following transducer realizes letter-wise
         absolute value::
 
             sage: T = transducers.abs([-1, 0, 1])
@@ -348,5 +379,6 @@ def abs(self, input_alphabet):
                           initial_states=[0],
                           final_states=[0])
 
+
 # Easy access to the transducer generators from the command line:
 transducers = TransducerGenerators()