# GIVEN

Introduces function parameters with their types. Used to declare what inputs a function accepts.

## Syntax

```l4
GIVEN name IS A Type

GIVEN name IS A Type, name2 IS A Type2

GIVEN name1 IS A Type1
      name2 IS A Type2
```

## Purpose

GIVEN declares the parameters of a function before the function definition. Each parameter has a name and a type.

## Examples

**Example file:** 

```l4-file
-- GIVEN keyword examples

-- Single Parameter Functions

GIVEN x IS A NUMBER
`double the value` x MEANS x TIMES 2

GIVEN `person name` IS A STRING
`greet the person` `person name` MEANS CONCAT "Hello, ", `person name`

#EVAL `double the value` 21
#EVAL `greet the person` "World"

-- Multiple Parameters (Same Line)

GIVEN a IS A NUMBER, b IS A NUMBER
`add two numbers` a b MEANS a PLUS b

GIVEN x IS A NUMBER, y IS A NUMBER
`multiply two numbers` x y MEANS x TIMES y

#EVAL `add two numbers` 10 32
#EVAL `multiply two numbers` 6 7

-- Multiple Parameters (Continuation with Indentation)

GIVEN x1 IS A NUMBER
      y1 IS A NUMBER
      z1 IS A NUMBER
`sum of three numbers` x1 y1 z1 MEANS x1 PLUS y1 PLUS z1

#EVAL `sum of three numbers` 1 2 3

-- Parameters with Complex Types

DECLARE Point HAS x IS A NUMBER, y IS A NUMBER

GIVEN p IS A Point
`get x coordinate` p MEANS p's x

GIVEN p1 IS A Point
      p2 IS A Point
`distance squared between points` p1 p2 MEANS
  LET `delta x` IS p2's x MINUS p1's x
      `delta y` IS p2's y MINUS p1's y
  IN (`delta x` TIMES `delta x`) PLUS (`delta y` TIMES `delta y`)

DECIDE `the origin` IS Point WITH x IS 0, y IS 0
DECIDE `point one` IS Point WITH x IS 3, y IS 4

#EVAL `get x coordinate` `point one`
#EVAL `distance squared between points` `the origin` `point one`

-- Type Parameters

GIVEN a IS A TYPE, xs IS A LIST OF a
GIVETH A NUMBER
`length of list` xs MEANS
  CONSIDER xs
  WHEN EMPTY THEN 0
  WHEN hd FOLLOWED BY tail THEN 1 PLUS `length of list` tail

#EVAL `length of list` (LIST 1, 2, 3, 4, 5)
#EVAL `length of list` (LIST "a", "b", "c")

-- Combined with GIVETH

GIVEN n IS A NUMBER
GIVETH A BOOLEAN
`is positive number` n MEANS n > 0

GIVEN num IS A NUMBER
GIVETH A STRING
`sign of number` num MEANS
  IF num > 0 THEN "positive"
  ELSE IF num < 0 THEN "negative"
       ELSE "zero"

#EVAL `is positive number` 5
#EVAL `sign of number` (-3)
```



### Single Parameter

```l4
GIVEN x IS A NUMBER
double x MEANS x TIMES 2
```

### Multiple Parameters (Same Line)

```l4
GIVEN a IS A NUMBER, b IS A NUMBER
add a b MEANS a PLUS b
```

### Multiple Parameters (Continuation)

Use indentation to continue the parameter list:

```l4
GIVEN x IS A NUMBER
      y IS A NUMBER
      z IS A NUMBER
sum3 x y z MEANS x PLUS y PLUS z
```

### With Type Parameters

```l4
GIVEN a IS A TYPE
GIVEN xs IS A LIST OF a
length xs MEANS
  CONSIDER xs
  WHEN EMPTY THEN 0
  WHEN _ FOLLOWED BY tail THEN 1 PLUS length tail
```

### With Complex Types

```l4
DECLARE Person HAS name IS A STRING, age IS A NUMBER

GIVEN p IS A Person
getName p MEANS p's name
```

## Annotations

Parameters can have NLG annotations:

```l4
GIVEN customer IS A Person @nlg
GIVEN amount IS A NUMBER @nlg
processPayment customer amount MEANS ...
```

## Related Keywords

- **[GIVETH](/l4/reference/functions/GIVETH.md)** - Specifies return type
- **[DECIDE](/l4/reference/functions/DECIDE.md)** - Function definition
- **[MEANS](/l4/reference/functions/MEANS.md)** - Function body
- **[TYPE-KEYWORDS](/l4/reference/types/keywords.md)** - Type syntax (IS, etc.)

## See Also

- **[Types Reference](/l4/reference/types.md)** - Available types