Your own functions

A handler that gives a value

A command does a job. A function works out a value and gives it back, like the built-in round or max. You write one with function instead of on, and send the value back with return. To use it, write its name with brackets around the values, anywhere a value can go.

function areaOf pWidth, pHeight
   return pWidth * pHeight
end areaOf

put areaOf(3, 4)
put areaOf(10, 2.5) + 1
put "A 6 by 7 room has" && areaOf(6, 7) && "square metres"

12
26
A 6 by 7 room has 42 square metres

The brackets are what tell xTalk you are calling a function. They are needed even when there are no values to pass: pickColour().

Functions that decide

A function can hold any lines you like: decisions, loops, other calls. As soon as a return runs, the function ends and hands back that value, so a function with several answers often has several return lines:

function parity pN
   if pN mod 2 is 0 then return "even"
   return "odd"
end parity

put 7 && parity(7)
put 10 && parity(10)

7 odd
10 even

Functions built from functions

Small functions that each do one thing are easy to test and easy to reuse. Bigger ones are then built out of them:

function fahrenheit pCelsius
   return pCelsius * 9 / 5 + 32
end fahrenheit

function describeTemp pCelsius
   return pCelsius & "C is" && fahrenheit(pCelsius) & "F"
end describeTemp

put describeTemp(100)
put describeTemp(-40)
put describeTemp(37)

100C is 212F
-40C is -40F
37C is 98.6F

A function's value can go straight into another call, as fahrenheit(pCelsius) does inside describeTemp, or into a chunk expression:

function shout pText
   return toUpper(pText) & "!"
end shout

put shout("hi") && shout("there")
put the number of chars of shout("abc")
put char 1 of shout("wow")

HI! THERE!
4
W

Giving back more than one value

A function returns one value, but a value can be a list. Return the parts as items or lines, and take them apart with chunk expressions where you use them:

function minMax pList
   return min(pList) & comma & max(pList)
end minMax

put minMax("4,9,1,7") into tBoth
put "smallest" && item 1 of tBoth & ", biggest" && item 2 of tBoth

smallest 1, biggest 9

For many named parts, an array is clearer. The lesson Arrays shows how.

Any number of values

Like commands, functions can read the paramCount and param(n), so one function can add up two numbers or twenty:

function total
   put 0 into tSum
   repeat with i = 1 to the paramCount
      add param(i) to tSum
   end repeat
   return tSum
end total

put total(1, 2, 3, 4)
put total(2.5, 2.5)
put total()

10
5
0

A function with no return

If a function ends without a return, it gives back empty. That is rarely what you meant, so when a function's value looks blank, check that every path through it reaches a return.

function forgetful pN
   put pN * 2 into tDouble
end forgetful

put "[" & forgetful(4) & "]"

[]

Brackets or "the"

Many of xTalk's own functions have two spellings: length(tName) and the length of tName are the same call. Your own functions always use brackets.

put "Lovelace" into tName
put length(tName)
put the length of tName
put the number of chars of tName

8
8
8

Private handlers

Put private before function or command and the handler can only be called from the same script. It is a way of saying "this is a helper; nothing else should rely on it", and xTalk can also call it a little faster.

private function secretNumber
   return 42
end secretNumber

put secretNumber()

42

function initials pName
   put empty into tLetters
   repeat for each word tWord in pName
      put toUpper(char 1 of tWord) after tLetters
   end repeat
   return tLetters
end initials

put initials("ada augusta lovelace")
put initials("Grace Hopper")

AAL
GH