---
title: QkQuantumRegister (latest version)
description: API reference for QkQuantumRegister in the latest version of qiskit-c
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-c/qk-quantum-register
---

# QkQuantumRegister

```c
typedef struct QkQuantumRegister QkQuantumRegister
```

A common way to instantiate several bits at once is to create a register. A register is a named collection of bits. Creating a register enables giving a collection of bits a name which can be use as metadata around specific bits in a circuit. This name will also typically be preseserved when exporting the circuit to interchange languages.

You can create a register by calling `qk_quantum_register_new()`, for example:

```c
#include <qiskit.h>

QkQuantumRegister *qreg = qk_quantum_register_new(5, "my_qreg");
```

Which creates a new 5 qubit register named `"my_qreg"`.

Then to add the register to a circuit you use the `qk_circuit_add_quantum_register()` function:

```c
QkCircuit *qc = qk_circuit_new(0, 0);
qk_circuit_add_quantum_register(qc, qreg);
uint32_t num_qubits = qk_circuit_num_qubits(qc); // 5
```

While circuits track registers, the registers themselves impart almost no behavioral differences on circuits.

## Functions

### qk\_quantum\_register\_new

`QkQuantumRegister *qk_quantum_register_new(uint32_t num_qubits, const char *name)`

Construct a new owning quantum register with a given number of qubits and name

#### Example

```c
QkQuantumRegister *qr = qk_quantum_register_new(5, "five_qubits");
```

#### Safety

The `name` parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator.

**Parameters**

- **num\_qubits** – The number of qubits to create the register for
- **name** – The name string for the created register. The name must be comprised of valid UTF-8 characters.

**Returns**

A pointer to the created register

### qk\_quantum\_register\_free

`void qk_quantum_register_free(QkQuantumRegister *reg)`

Free a quantum register.

#### Example

```c
QkQuantumRegister *qr = qk_quantum_register_new(1024, "qreg");
qk_quantum_register_free(qr);
```

#### Safety

Behavior is undefined if `reg` is not either null or a valid pointer to a `QkQuantumRegister`.

**Parameters**

- **reg** – A pointer to the register to free.

### qk\_quantum\_register\_name

`char *qk_quantum_register_name(const QkQuantumRegister *qreg)`

Get the name of a quantum register.

Returns a newly allocated C string containing the name of the quantum register.

#### Example

```c
QkQuantumRegister *qr = qk_quantum_register_new(5, "my_qreg");
char *name = qk_quantum_register_name(qr);
printf("Register name: %s\n", name);
qk_str_free(name);
qk_quantum_register_free(qr);
```

#### Safety

Behavior is undefined if `qreg` is not a valid, non-null pointer to a `QkQuantumRegister`.

**Parameters**

- **qreg** – A pointer to the quantum register.

**Returns**

A pointer to a newly allocated null-terminated string containing the register name. The caller must free this string using `qk_str_free`.

### qk\_quantum\_register\_num\_bits

`size_t qk_quantum_register_num_bits(const QkQuantumRegister *qreg)`

Get the number of bits in a quantum register.

Returns the size (number of bits) of the quantum register.

#### Example

```c
QkQuantumRegister *qr = qk_quantum_register_new(5, "my_qreg");
size_t num_qubits = qk_quantum_register_num_bits(qr);
printf("Number of qubits: %zu\n", num_qubits);  // Prints: 5
qk_quantum_register_free(qr);
```

#### Safety

Behavior is undefined if `qreg` is not a valid, non-null pointer to a `QkQuantumRegister`.

**Parameters**

- **qreg** – A pointer to the quantum register.

**Returns**

The number of bits in the register.

### qk\_quantum\_register\_circuit\_bits

`void qk_quantum_register_circuit_bits(const QkQuantumRegister *qreg, const QkCircuit *circuit, uint32_t *out_bits)`

Get the circuit bit indices for all qubits in a quantum register.

Outputs a mapping from each qubit in the quantum register to its corresponding index in the circuit’s qubit list. If a qubit from the register is not present in the circuit, its index in the mapping will be `UINT32_MAX`.

#### Example

```c
QkCircuit *qc = qk_circuit_new(2, 0);
QkQuantumRegister *qr = qk_quantum_register_new(3, "my_qreg");
qk_circuit_add_quantum_register(qc, qr);

uint32_t bit_indices[3];

qk_quantum_register_circuit_bits(qr, qc, bit_indices);

// bit_indices now contains [2, 3, 4] since all qubits are in the circuit
// and the circuit has 2 anonymous qubits

qk_quantum_register_free(qr);
qk_circuit_free(qc);
```

#### Safety

Behavior is undefined if:

- `qreg` is not a valid, non-null pointer to a `QkQuantumRegister`.
- `circuit` is not a valid, non-null pointer to a `QkCircuit`.
- `qreg` has one or more bits and `out_bits` is not an aligned, non-null pointer to an array with at least `qk_quantum_register_num_bits(qreg)` elements.

**Parameters**

- **qreg** – A pointer to the quantum register to map.
- **circuit** – A pointer to the circuit containing the qubits.
- **out\_bits** – A pointer to an array where the mapped indices will be written. The array must be pre-allocated with at least `qk_quantum_register_num_bits` elements for `qreg`. Each element will contain either the circuit bit index or `UINT32_MAX` if the qubit is not in the circuit.