std::memcpy
| Defined in header <cstring>
|
||
void* memcpy( void* dest, const void* src, std::size_t count ); |
||
Performs the following operations in order:
- Implicitly creates objects at
dest. - Copies
countcharacters (as if of typeunsigned char) from the object pointed to bysrcinto the object pointed to bydest.
If any of the following conditions is satisfied, the behavior is undefined:
destorsrcis a null pointer or invalid pointer.- Copying takes place between objects that overlap.
Parameters
| dest | - | pointer to the memory location to copy to |
| src | - | pointer to the memory location to copy from |
| count | - | number of bytes to copy |
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();
}
Output:
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.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 4064 | C++98 | it was unclear whether the returned pointer points to a suitable created object | made clear |
See also
| moves one buffer to another (function) | |
| fills a buffer with a character (function) | |
| copies a certain amount of wide characters between two non-overlapping arrays (function) | |
| copies characters (public member function of std::basic_string<CharT,Traits,Allocator>)
| |
(C++11) |
copies a range of elements to a new location (function template) |
| copies a range of elements in backwards order (function template) | |
(C++11) |
checks if a type is trivially copyable (class template) |
C documentation for memcpy
| |