# std::subtract_with_carry_engine

> C++ Atlas: `cppatlas.com/w/cpp/numeric/random/subtract_with_carry_engine` | Source: https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine | Domain: Numerics | Standards: C++11, C++20

Is a random number engine that uses subtract with carry algorithm.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <random>

template<
    class UIntType,
    std::size_t w, std::size_t s, std::size_t r
> class subtract_with_carry_engine; // (since C++11)
```

Is a random number engine that uses subtract with carry algorithm.

### Template parameters

- `UIntType` - The result type generated by the generator. The effect is undefined if this is not one of `unsigned short`, `unsigned int`, `unsigned long`, or `unsigned long long`.
- `w` - the word size, in bits, of the state sequence
- `s` - the short lag
- `r` - the long lag

If `w` is not in `[1,` `std::numeric_limits<UIntType>::digits]`, or `s` is not in `[1,` `r)`, the program is ill-formed.

### Generator properties

The size of the states of `subtract_with_carry_engine` is O(r), each of them consists of two parts:

- A sequence `X` of `r` integer values, where each value is in `[​0​,` `2w)`.
- An integer `c` (known as the *carry*), whose value is either `​0​` or `1`.

Given that X^(j) stands for the j mod rth value (starting from 0) of `X`, the transition algorithm of `subtract_with_carry_engine` (TA(xⁱ)) is defined as follows:

1. Let `Y` be X^(i-s)-X^(i-r)-c.
2. Let `y` be Y mod 2^(w), and set Xⁱ to `y`.
3. If `Y` is negative, set `c` to `1`, otherwise set `c` to `​0​`.

The generation algorithm of `subtract_with_carry_engine` is GA(xⁱ) = y, where `y` is the value produced in step 2 of the transition algorithm.

### Predefined specializations

The following specializations define the random number engine with two commonly used parameter sets:

Defined in header `<random>`

**Type — Definition**

- `ranlux24_base` (C++11): `std::subtract_with_carry_engine<std::uint_fast32_t, 24, 10, 24>`
- `ranlux48_base` (C++11): `std::subtract_with_carry_engine<std::uint_fast64_t, 48, 5, 12>`

### Nested types

**Type — Definition**

- `result_type`: `UIntType`

### Data members

- `constexpr std::size_t word_size` [static]: `w` (public static member constant)
- `constexpr std::size_t short_lag` [static]: `s` (public static member constant)
- `constexpr std::size_t long_lag` [static]: `r` (public static member constant)
- `constexpr std::uint_least32_t default_seed` [static]: `19780503u` (public static member constant)

### Member functions

**Construction and Seeding**

- (constructor): constructs the engine (public member function)
- `seed`: sets the current state of the engine (public member function)

**Generation**

- `operator()`: advances the engine's state and returns the generated value (public member function)
- `discard`: advances the engine's state by a specified amount (public member function)

**Characteristics**

- `min` [static]: gets the smallest possible value in the output range (public static member function)
- `max` [static]: gets the largest possible value in the output range (public static member function)

### Non-member functions

- `operator==` (C++11), `operator!=` (C++11)(removed in C++20): compares the internal states of two pseudo-random number engines (function)
- `operator<<` (C++11), `operator>>`: performs stream input and output on pseudo-random number engine (function template)

### Example

> Note: This section is incomplete Reason: no example

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 3809 | C++11 | `default_seed` might not be representable with `result_type` | changed its type to `std::uint_least32_t` |

---
Attribution: content from https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.