# format

## Category
String

## Arity
**Unary** — `format [template, arg1, arg2, ...]`.

```
format <array>   // [template, arg1, arg2, ...]
```

## Description
Formats a string using `%1`, `%2`, ... placeholders replaced by the corresponding arguments. The right operand is an array where the first element is the template string, followed by substitution values. This matches Arma SQF `format` behavior.

## How It Works
Parses the template string for `%N` tokens (where N is a 1-based index). Each token is replaced with `str` of the corresponding argument from the array. Arguments beyond the template are ignored. Missing placeholders remain unchanged.

## Usage

### Basic formatting
```sqf
_result = format ["HP: %1/%2", _hp, _maxHp];  // "HP: 75/100"
```

### Named-style output
```sqf
_msg = format ["%1 killed %2 with %3", _killer, _victim, _weapon];
```

### Debug messages
```sqf
diag_log format ["Frame %1: %2 units, %3 FPS", _frame, count _units, _fps];
```

### Coordinates / vectors
```sqf
_posStr = format ["[%1, %2, %3]", _x, _y, _z];
```

### Multi-line
```sqf
_report = format ["Name: %1\nScore: %2\nRank: %3", _name, _score, _rank];
```

### vs f-strings
SQ# also supports f-strings (compile-time):
```sqf
// format (runtime)
_msg = format ["Hello %1", _name];

// f-string (compile-time, preferred when possible)
_msg = f"Hello {_name}";
```

Prefer f-strings when the template is known at compile time. Use `format` when the template is dynamic (loaded from config, user input, etc.).

## Thread Safety
ReadOnly — pure computation, no side effects. Safe from any scheduler.

## See Also
- [str](str.md) — simple value to string
- [+](add-operator.md) — string concatenation
- [parseNumber](parseNumber.md) — parse number from string