# Session 7

*Commands & Functions*

You should be pretty familiar with commands by now. Just copy the names of buttons or menu items into your script and add some arguments if necessary—that's it (or use command history). En passant, I've introduced you to a quite similar construct in the previous sessions: built-in functions. Examples of built-in functions are `number ()`

, `string$ ()`

, `selected ()`

, or `extractWord$ ()`

. They have much in common with commands but you won't find them in the GUI. They consist of a function name, followed by a (optional) space and a list of arguments enclosed in round brackets. You're not allowed to omit the brackets, even if the arguments list is empty. Within the brackets, the same rules as for command arguments apply: arguments have a fixed order, are separated by commas, and are wrapped in double quotes if they are literal strings.

### Return value

Functions always yield a return value and the name of the function tells you the type of its return value. If the name ends with *$* the function returns a string, if there's no *$* it returns a number. In fact, there are some functions that come in two flavors: with and without a *$*. An example you already know is `selected ()`

and `selected$ ()`

. `selected ()`

yields a numeric return value (object ID), while `selected$ ()`

yields a string value (object type+name).

Since functions are not part of the GUI, you can't use command history to insert them into your scripts. Instead, you have to type them by hand. That's a pity, but it's worth the effort, because the benefit of functions is immense. Many operations can't be implemented without functions and many operations are seriously simplified by using functions.

Praat provides three types of built-in functions: 'management functions', mathematical functions, and string functions. Management functions like `selected ()`

`selected$ ()`

`fileReadable ()`

to ascertain whether a certain file is readable or `exitScript ()`

to abort a script before the end is reached.

Mathematical and string functions are listed in the formulas tutorial of the Praat manual. Choose `round ()`

(round a real number to the nearest integer), `sqrt ()`

(calculate square root), or `sin ()`

(calculate sine). Besides, there are some advanced statistical and conversion functions. Among the string functions you'll find functions to analyze strings (e.g. `length ()`

counts the number of characters), extract substrings (e.g. `extractWord$ ()`

), modify strings (delete/add/replace substrings; e.g. `replace$ ()`

), and convert strings (e.g. `number ()`

`string$ ()`

Most of the time, return values of functions are assigned to variables:

```
type_name$ = selected$ ()
type$ = extractWord$ (type_name$, "")
```

### Functions as arguments

But it's also possible (in most contexts) to replace literal values with functions. In this case, functions behave like variables. For example, you can combine the two statements above into one statement:

```
type$ = extractWord$ (selected$ (), "")
```

First, `selected$ ()`

is replaced by its return value (type+name of the selected object) like variables are replaced by their content, then `extractWord$ ()`

kicks in and the result is assigned to *type$*.

Another example: The query command `round ()`

or (2) preserve some decimal places and round the maximum to e.g. 2 digits after the decimal point. The latter can be done with the string function `fixed$ ()`

; `fixed$ ()`

takes two arguments, a number (in our case the pitch maximum) and the precision you wish (number of decimal places, e.g. 2). Since `fixed$ ()`

*$*, it returns a string, therefore we must assign it to a string variable:

```
# query pitch maximum
pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
# round; result: integer number
pitchMaxInt = round (pitchMax)
# round with fixed precision; result: string (sequence of digits)
pitchMaxFix$ = fixed$ (pitchMax, 2)
writeInfoLine: pitchMaxInt, tab$, pitchMaxFix$
```

To avoid the entire variable assignment, we can insert the functions directly as arguments of `writeInfoLine`

:

```
pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
writeInfoLine: round (pitchMax), tab$, fixed$ (pitchMax, 2)
```

And what if we want to use the result of `fixed$ ()`

as a number? Well, we simply convert it back, from string to number with the `number ()`

function:

```
pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
# round with fixed precision; result: string
pitchMaxFix$ = fixed$ (pitchMax, 2)
# convert string to number
pitchMaxFix = number (pitchMaxFix$)
```

Again, we're allowed to cut a corner by using a function as an argument instead of assigning its return value to a variable:

```
pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
pitchMaxFix = number (fixed$ (pitchMax, 2))
```

## Recap

upcoming...