◆ memneg_BE()

bool Chusov::Memory::memneg_BE	(	void *	pDest,
		std::size_t	cbDest,
		const void *	pSrc,
		std::size_t	cbSrc
	)

noexcept

Zero-extends or contracts an arbitrary-precision integer given in the Big-Endian byte order, then computes an additive inversion of it in a separate of the same destination buffer returning a value of the highest bit of the result.

Parameters

[out]	pDest	A pointer to the destination buffer which receives a two's complement of the input integer with respect to 2^{CHAR_BIT cbDest}.
	cbDest	Capacity of the destination buffer and length of the resulting integer in bytes.
[in]	pSrc	A pointer to an input integer to negate by the function. The buffer may be the same as the destination buffer. Other than that, the buffers may not overlap.
	cbSrc	Length of the input integer in bytes. If `cbSrc` is less than `cbDest`, then the input integer is zero-extended to `cbDest` bytes before the negation. Otherwise, if `cbSrc` is greater than `cbDest`, then `cbSrc - cbDest` high-order bytes of the input are discarded.

Returns: A value of the highest bit of the result, i.e. the value of the highest bit in the byte pDest[0], if cbDest is greater than zero, or zero otherwise.

The function considers the input vector to specify the integer in the Big-Endian byte order. That is, given that \(V_X = \{x_0, \dots, x_n\}\) is the input vector pointed to by pSrc, such that \(x_0\) is the first byte in memory of the vector, \(x_n\) is the last byte and n = cbSrc - 1, the input value for the operation is \(X = \sum_{i=0}^{n}x_{n-i}\cdot b^i\), where b = 2^CHAR_BIT is a number of values that can be represented with one byte.

The operation is performed modulo \(b^{\textrm{cbDest}}\). That is, before the negation takes place the input value \(X\) is zero-extended or contracted to fit the buffer of cbDest bytes producing the value \(X' = \sum_{i=0}^{m}x'_i\cdot b^i\), where m = cbDest - 1, \(x'_i = x_{n-i}\) if \(0 \le i \le n\), and \(x'_i = 0\) otherwise. The value \(X'\) is then negated and written into the destination buffer pDest, again, in the Big-Endian byte order.

To negate Little-Endian integers use memneg_LE.

If the sizes of the input and output integers are equal, and it is known beforehand whether the two buffers are different or the two pointers address the same memory, the preferable faster functions for the operation are memneg_BE_copy and memneg_BE_inplace.

See also: memneg_BE_copy;
memneg_BE_inplace;
memneg_LE;
memincr_BE;
memdecr_BE;
memadd_BE;
memsub_BE.