std:: memcpy

Performs the following operations in order:

1. Implicitly creates objects at dest .
2. Copies count characters (as if of type unsigned char ) from the object pointed to by src into the object pointed to by dest .

If any of the following conditions is satisfied, the behavior is undefined:

• dest or src is a null pointer or invalid pointer .
• Copying takes place between objects that overlap.

Parameters

Return value

If there is a suitable created object , returns a pointer to it; otherwise returns dest .

Notes

std::memcpy is meant to be the fastest library routine for memory-to-memory copy. It is usually more efficient than std::strcpy , which must scan the data it copies or std::memmove , which must take precautions to handle overlapping inputs.

Several C++ compilers transform suitable memory-copying loops to std::memcpy calls.

Where strict aliasing prohibits examining the same memory as values of two different types, std::memcpy may be used to convert the values.

Example

#include <cstdint>
#include <cstring>
#include <iostream>
int main()
{
    // simple usage
    char source[] = "once upon a daydream...", dest[4];
    std::memcpy(dest, source, sizeof dest);
    std::cout << "dest[4] = {";
    for (int n{}; char c : dest)
        std::cout << (n++ ? ", " : "") << '\'' << c << "'";
    std::cout << "};\n";
    // reinterpreting
    double d = 0.1;
//  std::int64_t n = *reinterpret_cast<std::int64_t*>(&d); // aliasing violation
    std::int64_t n;
    std::memcpy(&n, &d, sizeof d); // OK
    std::cout << std::hexfloat << d << " is " << std::hex << n
              << " as a std::int64_t\n" << std::dec;
    // object creation in destination buffer
    struct S
    {
        int x{42};
        void print() const { std::cout << '{' << x << "}\n"; }
    } s;
    alignas(S) char buf[sizeof(S)];
    S* ps = new (buf) S; // placement new
    std::memcpy(ps, &s, sizeof s);
    ps->print();
}

dest[4] = {'o', 'n', 'c', 'e'};
0x1.999999999999ap-4 is 3fb999999999999a as a std::int64_t
{42}

Defect reports

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

See also