Namespaces
Variants
Views
Actions

Difference between revisions of "c/string/wide/wmemcpy"

From cppreference.com
< c‎ | string‎ | wide
(templatization)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{c/title|wmemcpy}}
+
{{c/title|wmemcpy|wmemcpy_s}}
 
{{c/string/wide/navbar}}
 
{{c/string/wide/navbar}}
−
{{ddcl | header=wchar.h |
+
{{dcl begin}}
 +
{{dcl header | wchar.h}}
 +
{{dcl rev begin|num=1}}
 +
{{dcl | until=c99 | since=c95 |
 
wchar_t* wmemcpy( wchar_t* dest, const wchar_t* src, size_t count );
 
wchar_t* wmemcpy( wchar_t* dest, const wchar_t* src, size_t count );
 
}}
 
}}
−
 
+
{{dcl | since=c99 |
−
Copies {{tt|count}} wide characters from the object pointed to by {{tt|src}} to the object pointed to by {{tt|dest}}. If the objects overlap, the behavior is undefined.
+
wchar_t *wmemcpy(wchar_t *restrict dest, const wchar_t *restrict src,
 +
                size_t count );
 +
}}
 +
{{dcl rev end}}
 +
{{dcl | since=c11 |num=2|
 +
errno_t wmemcpy_s( wchar_t *restrict dest, rsize_t destsz,
 +
                  const wchar_t *restrict src, rsize_t count );
 +
}}
 +
{{dcl end}}
 +
@1@ Copies exactly {{tt|count}} successive wide characters from the wide character array pointed to by {{tt|src}} to the wide character array pointed to by {{tt|dest}}. If the objects overlap, the behavior is undefined. If {{tt|count}} is zero, the function does nothing.
 +
@2@ Same as {{v|1}}, except that the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
 +
:* {{tt|src}} or {{tt|dest}} is a null pointer
 +
:* {{tt|destsz}} or {{tt|count}} is greater than {{c|RSIZE_MAX/sizeof(wchar_t)}}
 +
:* {{tt|count}} is greater than {{tt|destsz}} (overflow would occur)
 +
:* overlap would occur between the source and the destination arrays
 +
:{{c/ext1 availability|wmemcpy_s}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | dest | pointer to the memory location to copy to}}
+
{{par | dest | pointer to the wide character array to copy to}}
−
{{par | src | pointer to the memory location to copy from}}
+
{{par | src | pointer to the wide character array to copy from}}
 
{{par | count | number of wide characters to copy}}
 
{{par | count | number of wide characters to copy}}
 +
{{par | destsz | max number of wide characters to write (the size of the destination buffer)}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{tt|dest}}
+
@1@ returns a copy of {{tt|dest}}
 +
@2@ returns zero on success, returns non-zero on error. Also, on error, fills the entire {{tt|dst}} up to and not including {{c|dst+dstsz}} with null wide characters, {{c|L'\0'}} (unless {{tt|dest}} is null or {{tt|destsz}} is greater than {{c|RSIZE_MAX/sizeof(wchar_t)}})
 +
 
 +
===Notes===
 +
This function's analog for byte strings is {{lc|strncpy}}, not {{lc|strcpy}}.
 +
 
 +
This function is not locale-sensitive and pays no attention to the values of the {{c|wchar_t}} objects it copies: nulls as well as invalid characters are copied too.
  
 
===Example===
 
===Example===
Line 21: Line 46:
 
  |
 
  |
 
  | code=
 
  | code=
 +
#include <stdio.h>
 +
#include <wchar.h>
 +
#include <locale.h>
 +
 +
int main(void)
 +
{
 +
    wchar_t from1[] = L"नमस्ते";
 +
    size_t sz1 = sizeof from1 / sizeof *from1;
 +
    wchar_t from2[] = L"Բարև";
 +
    size_t sz2 = sizeof from2 / sizeof *from2;
 +
    wchar_t to[sz1 + sz2];
 +
    wmemcpy(to, from1, sz1); // copy from1, along with its null terminator
 +
    wmemcpy(to + sz1, from2, sz2); // append from2, along with its null terminator
 +
 +
    setlocale(LC_ALL, "en_US.utf8");
 +
    printf("Wide array contains: ");
 +
    for(size_t n = 0; n < sizeof to / sizeof *to; ++n)
 +
        if(to[n])
 +
            printf("%lc", to[n]);
 +
        else
 +
            printf("\\0");
 +
    printf("\n");
 +
}
 +
|p=true
 
  | output=
 
  | output=
 +
Wide array contains: नमस्ते\0Բարև\0
 
}}
 
}}
 +
 +
===References===
 +
{{ref std c11}}
 +
{{ref std | section=7.29.4.2.3  | title=The wmemcpy function | p=431}}
 +
{{ref std | section=K.3.9.2.1.3 | title=The wmemcpy_s function | p=641}}
 +
{{ref std c99}}
 +
{{ref std | section=7.24.4.2.3  | title=The wmemcpy function | p=377}}
 +
{{ref std end}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
 
{{dsc inc | c/string/wide/dsc wmemmove}}
 
{{dsc inc | c/string/wide/dsc wmemmove}}
 +
{{dsc inc | c/string/byte/dsc strncpy}}
 
{{dsc see cpp | cpp/string/wide/wmemcpy}}
 
{{dsc see cpp | cpp/string/wide/wmemcpy}}
 
{{dsc end}}
 
{{dsc end}}
  
 +
[[ar:c/string/wide/wmemcpy]]
 +
[[cs:c/string/wide/wmemcpy]]
 
[[de:c/string/wide/wmemcpy]]
 
[[de:c/string/wide/wmemcpy]]
 
[[es:c/string/wide/wmemcpy]]
 
[[es:c/string/wide/wmemcpy]]
Line 35: Line 96:
 
[[it:c/string/wide/wmemcpy]]
 
[[it:c/string/wide/wmemcpy]]
 
[[ja:c/string/wide/wmemcpy]]
 
[[ja:c/string/wide/wmemcpy]]
 +
[[ko:c/string/wide/wmemcpy]]
 +
[[pl:c/string/wide/wmemcpy]]
 
[[pt:c/string/wide/wmemcpy]]
 
[[pt:c/string/wide/wmemcpy]]
 
[[ru:c/string/wide/wmemcpy]]
 
[[ru:c/string/wide/wmemcpy]]
 +
[[tr:c/string/wide/wmemcpy]]
 
[[zh:c/string/wide/wmemcpy]]
 
[[zh:c/string/wide/wmemcpy]]

Latest revision as of 15:51, 30 April 2018

 
C
 
Strings library
 
Null-terminated wide strings
Functions
Character manipulation
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C99)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
Conversions to numeric formats
(C95)(C99)
(C95)(C99)
(C99)(C95)(C99)
(C99)(C99)
String manipulation
(C95)(C11)
(C95)(C11)
(C95)(C11)
(C95)(C11)
(C95)(C11)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)(C11)
Array manipulation
wmemcpywmemcpy_s
(C95)(C11)
(C95)(C11)
(C95)
(C95)
(C95)
 
Defined in header <wchar.h>
(1)
wchar_t* wmemcpy( wchar_t* dest, const wchar_t* src, size_t count );
 (since C95)
(until C99)
wchar_t *wmemcpy(wchar_t *restrict dest, const wchar_t *restrict src,
                 size_t count );
 (since C99)
errno_t wmemcpy_s( wchar_t *restrict dest, rsize_t destsz,
                   const wchar_t *restrict src, rsize_t count );
 (2) (since C11)
1) Copies exactly count successive wide characters from the wide character array pointed to by src to the wide character array pointed to by dest. If the objects overlap, the behavior is undefined. If count is zero, the function does nothing.
2) Same as (1), except that the following errors are detected at runtime and call the currently installed constraint handler function:
  • src or dest is a null pointer
  • destsz or count is greater than RSIZE_MAX/sizeof(wchar_t)
  • count is greater than destsz (overflow would occur)
  • overlap would occur between the source and the destination arrays
As with all bounds-checked functions, wmemcpy_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.

Contents

[edit] Parameters

dest - pointer to the wide character array to copy to
src - pointer to the wide character array to copy from
count - number of wide characters to copy
destsz - max number of wide characters to write (the size of the destination buffer)

[edit] Return value

1) returns a copy of dest
2) returns zero on success, returns non-zero on error. Also, on error, fills the entire dst up to and not including dst+dstsz with null wide characters, L'\0' (unless dest is null or destsz is greater than RSIZE_MAX/sizeof(wchar_t))

[edit] Notes

This function's analog for byte strings is strncpy, not strcpy.

This function is not locale-sensitive and pays no attention to the values of the wchar_t objects it copies: nulls as well as invalid characters are copied too.

[edit] Example

Run this code
#include <stdio.h>
#include <wchar.h>
#include <locale.h>
 
int main(void)
{
    wchar_t from1[] = L"नमस्ते";
    size_t sz1 = sizeof from1 / sizeof *from1;
    wchar_t from2[] = L"Բարև";
    size_t sz2 = sizeof from2 / sizeof *from2;
    wchar_t to[sz1 + sz2];
    wmemcpy(to, from1, sz1); // copy from1, along with its null terminator
    wmemcpy(to + sz1, from2, sz2); // append from2, along with its null terminator
 
    setlocale(LC_ALL, "en_US.utf8");
    printf("Wide array contains: ");
    for(size_t n = 0; n < sizeof to / sizeof *to; ++n)
        if(to[n])
            printf("%lc", to[n]);
        else
            printf("\\0");
    printf("\n");
}

Possible output: 

Wide array contains: नमस्ते\0Բարև\0

[edit] References

  • C11 standard (ISO/IEC 9899:2011):
  • 7.29.4.2.3 The wmemcpy function (p: 431)
  • K.3.9.2.1.3 The wmemcpy_s function (p: 641)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.24.4.2.3 The wmemcpy function (p: 377)

[edit] See also

(C95)(C11)
 copies a certain amount of wide characters between two, possibly overlapping, arrays
(function) [edit]
(C11)
 copies a certain amount of characters from one string to another
(function) [edit]
C++ documentation for wmemcpy
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=c/string/wide/wmemcpy&oldid=101824"