# std::subtract_with_carry_engine

From cppreference.com
< cpp‎ | numeric‎ | random

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 \(\scriptsize O(r)\)O(r), each of them consists of two parts:

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

Given that \(\scriptsize X_j\)Xj stands for the \(\scriptsize j\mod r\)j mod rth value (starting from 0) of X, the transition algorithm of `subtract_with_carry_engine` (\(\scriptsize TA(x_i)\)TA(xi)) is defined as follows:

1. Let Y be \(\scriptsize X_{i-s}-X_{i-r}-c\)Xi-s-Xi-r-c.
2. Let y be \(\scriptsize Y\mod 2^w\)Y mod 2w
   , and set \(\scriptsize X_i\)Xi 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 \(\scriptsize GA(x_i) = y\)GA(xi) = 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==operator!= (C++11)(C++11)(removed in C++20) | compares the internal states of two pseudo-random number engines (function)
operator<<operator>> (C++11) | performs stream input and output on pseudo-random number engine (function template)

### Example

| 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

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/random/subtract_with_carry_engine&oldid=175313"