# sub()

Returns the result of subtracting two values or subtracting a value from each item in a list or subtracting pairwise the items in two lists.

## Synopsis

```sub(x, y)
```

## Description

If `x` and `y` are single-valued expression, the function returns the difference of the two given values, `x - y`.

If the first argument is a single-valued expression and the other is a list-expression, then the function returns is a list of values consisting of the difference of the single value and each item in the list.

If the first argument is a list-valued expression and the other is a single-valued expression, then the function returns is a list of values consisting of the difference each item in the list and the single value.

If both arguments are list-expressions, then the function returns is a list of values consisting of the difference between the items in the first list and the corresponding items in the second list. In this case, the lists must have the same number of items.

This function is the prefix notation for the expression `x - y`.

## Parameters

`x`

An expression that evaluates to a number or a list.

`y`

An expression that evaluates to a number or a list.

## Returns

The result is a single value if both arguments are single-valued expressions; otherwise the result is a list.

## Errors

If both arguments are list-expressions, a run-time error occurs if the lists have different lengths.

## Examples

```z = sub(3, 1)  # z = 1
z = 3 - 1      # z = 1

a_list = list(1, 2, 3)
new_list = sub(a_list, 1)  # new_list = list(0, 1, 2)
new_list = a_list - 1      # new_list = list(0, 1, 2)
new_list = 10 - a_list     # new_list = list(9, 8, 7)

a_list = list(10, 20, 30)
b_list = list(1, 2, 3)
new_list = a_list - b_list  # new_list = list(9, 18, 27)
```