Updates to Grist Functions (#125)

Clarify documentation for QUOTIENT, SUMPRODUCT, UUID, REPLACE, lookupOne, lookupRecords, and $group.

sandbox/grist/functions/math.py

@@ -550,7 +550,7 @@ def PRODUCT(factor1, *more_factors):
 
 def QUOTIENT(dividend, divisor):
   """
-  Returns one number divided by another.
+  Returns one number divided by another, without the remainder.
 
   >>> QUOTIENT(5, 2)
   2
@@ -797,7 +797,8 @@ def SUMIFS(sum_range, criteria_range1, criterion1, *args):
 
 def SUMPRODUCT(array1, *more_arrays):
   """
-  Multiplies corresponding components in the given arrays, and returns the sum of those products.
+  Multiplies corresponding components in two equally-sized arrays, 
+  and returns the sum of those products.
 
   >>> SUMPRODUCT([3,8,1,4,6,9], [2,6,5,7,7,3])
   156
@@ -859,7 +860,13 @@ def TRUNC(value, places=0):
   return ROUNDDOWN(value, places)
 
 def UUID():
-  """Generate a random UUID-formatted string identifier."""
+  """
+  Generate a random UUID-formatted string identifier. 
+  Since UUID() produces a different value each time it's called, it is best to use it in 
+  [trigger formula](https://support.getgrist.com/formulas/#trigger-formulas) for new records. 
+  This would only calculate UUID() once and freeze the calculated value. By contrast, a regular [formula] 
+  may get recalculated any time the document is reloaded, producing a different value for UUID() each time.
+  """
   if six.PY2:
     return str(uuid.UUID(bytes=[chr(random.randrange(0, 256)) for _ in xrange(0, 16)], version=4))
   else:

sandbox/grist/functions/text.py

@@ -220,7 +220,9 @@ def LEFT(string, num_chars=1):
 
 def LEN(text):
   """
-  Returns the number of characters in a text string. Same as `len(text)`.
+  Returns the number of characters in a text string, or the number of items in a list. Same as 
+  [`len`](https://docs.python.org/3/library/functions.html#len) in python. 
+  See [Record Set](https://support.getgrist.com/functions/#recordset) for an example of using `len` on a list of records.
 
   >>> LEN("Phoenix, AZ")
   11
@@ -339,9 +341,9 @@ def REGEXREPLACE(text, regular_expression, replacement):
   return re.sub(regular_expression, replacement, text)
 
 
-def REPLACE(old_text, start_num, num_chars, new_text):
+def REPLACE(text, position, length, new_text):
   """
-  Replaces part of a text string with a different text string. Start_num is counted from 1.
+  Replaces part of a text string with a different text string. Position is counted from 1.
 
   >>> REPLACE("abcdefghijk", 6, 5, "*")
   'abcde*k'
@@ -354,11 +356,11 @@ def REPLACE(old_text, start_num, num_chars, new_text):
   >>> REPLACE('foo', 0, 1, 'bar')
   Traceback (most recent call last):
   ...
-  ValueError: start_num invalid
+  ValueError: position invalid
   """
-  if start_num < 1:
+  if position < 1:
-    raise ValueError("start_num invalid")
+    raise ValueError("position invalid")
-  return old_text[:start_num - 1] + new_text + old_text[start_num - 1 + num_chars:]
+  return text[:position - 1] + new_text + text[position - 1 + length:]
 
 
 def REPT(text, number_times):

sandbox/grist/records.py

@@ -38,8 +38,9 @@ class Record(object):
     Name: $group, rec.group
     Usage: __$group__
 
-    In a summary view, `$group` is a special field containing the list of Records that are
+    In a [summary table](https://support.getgrist.com/summary-tables/), `$group` is a special field 
-    summarized by the current summary line. E.g. `len($group)` is the count of those records.
+    containing the list of Records that are summarized by the current summary line.  E.g. the formula 
+    `len($group)` counts the number of those records being summarized in each row.
 
     See [RecordSet](#recordset) for useful properties offered by the returned object.
 

sandbox/grist/table.py

@@ -79,13 +79,18 @@ class UserTable(object):
   # and we decided camelCase was a more user-friendly choice for user-facing functions.
   def lookupRecords(self, **field_value_pairs):
     """
-    Returns the Records from this table that match the given field=value arguments. If
+    Name: lookupRecords
-    `sort_by=field` is given, sort the results by that field.
+    Usage: UserTable.__lookupRecords__(Field_In_Lookup_Table=value, ...)
+    Returns a RecordSet matching the given field=value arguments. The value may be any expression, 
+    most commonly a field in the current row (e.g. `$SomeField`) or a constant (e.g. a quoted string 
+    like `"Some Value"`) (examples below). 
+    If `sort_by=field` is given, sort the results by that field.
 
     For example:
     ```
-    People.lookupRecords(Last_Name="Johnson", sort_by="First_Name")
+    People.*lookupRecords*(Email=$Work_Email)
-    People.lookupRecords(First_Name="George", Last_Name="Washington")
+    People.*lookupRecords*(First_Name="George", Last_Name="Washington")
+    People.*lookupRecords*(Last_Name="Johnson", sort_by="First_Name")
     ```
 
     See [RecordSet](#recordset) for useful properties offered by the returned object.
@@ -98,12 +103,17 @@ class UserTable(object):
 
   def lookupOne(self, **field_value_pairs):
     """
-    Returns a Record matching the given field=value arguments. If multiple records match, returns
+    Name: lookupOne
-    one of them. If none match, returns the special empty record.
+    Usage: UserTable.__lookupOne__(Field_In_Lookup_Table=value, ...)
+    Returns a Record matching the given field=value arguments. The value may be any expression, 
+    most commonly a field in the current row (e.g. `$SomeField`) or a constant (e.g. a quoted string 
+    like `"Some Value"`). If multiple records match, returns one of them. If none match, returns the 
+    special empty record.
 
     For example:
     ```
-    People.lookupOne(First_Name="Lewis", Last_Name="Carroll")
+    People.*lookupOne*(First_Name="Lewis", Last_Name="Carroll")
+    People.*lookupOne*(Email=$Work_Email)
     ```
     """
     return self.table.lookup_one_record(**field_value_pairs)