Using Python functions as UDF()

Using the built-in UDF() (user-defined-) function you can call any Python modules/functions in formulas in GS-Calc.
This can help you to significantly increase GS-Calc functionality thanks to the large number of various Python modules and libraries including, for example, science, finance, graphics.

From GS-Calc you can pass to Python functions any type of parameters: (double precision) numbers, text strings, ranges as numeric arrays/matrices, automatically saved blocks of CSV data from ranges.

GS-Calc can accept from Python functions any type of data it supports in formulas: (double precision) numbers, text strings, numeric arrays/matrices, 2d arrays of any size and with any cell contents passed to GS-Calc as CSV data blocks to parse and finally images/graphics (that can overflow the formula cells).

The UDF() function:

UDF(module, function, type, parameter1, parameter2, ...)

module - Python module name with full path, for example "c:\my_modules\some_functions.py"
function - function name as it appear in the above module, for example "my_function"
type - an index (0-5) specifying what type of data GS-Calc should expect from the Python procedure. Possible values are:
- 0 - a number
- 1 - a matrix/array of numbers
- 2 - a text string (up to 1024 characters)
- 3 - a string/block of CSV data (of any size) to be pasted without parsing numbers in cells
- 4 - a string/block of CSV data (of any size) to be pasted with parsing numbers in cells
- 5 - an image (binary data returned as standard Python "memoryview" binary data)
Additionally, you can add to the "type" parameter the following flags:
32 - all ranges/arrays passed from GS-Calc to Python will be saved and pass to Python as blocks/strings of CSV data
64 - same as 32 except that CSV data is created and pass instead of an array only if there any non-numeric/text cells within that GS-Calc range/array.

If neither 32 nor 64 is used, if you specify a range as a parameter in the UDF() function, GS-Calc will pass it as an array of numbers ignoring any text data. Rules used to save and parse such CSV data blocks are the same as for handling regular CSV files in GS-Calc.

Python modules are plain text files with the "*.py" extension. Below is an example of such a file containing seven simple functions.

e:\example.py :


def function1():
   return 10

def function2(a, b):
  return a + b

def function3(text):
   return 'A new text with ' + text + ' inserted in the middle'

def function4():
   csvdata = 'abc,def,ghi\n123,456,789'
   return csvdata

def function5(csvdata):
   return csvdata

def function6(csvFilePath):
   f = open(csvFilePath, 'rb')
   file_content = f.read()
   f.close()
   return file_content

def function7(imageFilePath):
   f = open(imageFilePath, 'rb')
   file_content = f.read()
   f.close()
   return bytearray(file_content)

In GS-Calc the above functions can be use as follows:

1.UDF("e:\example.py", "function1", 0)

takes no arguments and returns 10
2. UDF("e:\example.py", "function2", 0, 10, 20)

returns the sum of two numbers
3. UDF("e:\example.py", "function3", 2, "a word")

takes a text string, inserts it in another string and returns the obtained new string to GS-Calc
4. UDF("e:\example.py", "function4", 4)

uses no arguments and returns CSV data block which then fills a given 2 rows x 3 columns range in GS-Calc with these 6 values
5. UDF("e:\example.py", "function5", 4 + 32, b10:d10000)

accepts from GS-Calc a CSV data block and returns it back for parsing in GS-Calc
6. UDF("e:\example.py", "function6", 4, "e:\some_csv_file.csv")

loads a CSV file and returns its contents for parsing in GS-Calc
7. UDF("e:\example.py", "function7", 5, "e:\some_image.jpg")

returns a jpeg/png/gif/bmp/tiff image loaded from the specified file; GS-Calc will display it in its original size, overflowing cells below and to the right if necessary