Namespaces
Variants

wcsncpy, wcsncpy_s

From cppreference.net
< c ‎ | string ‎ | wide
C
Strings library
Null-terminated wide strings
Défini dans l'en-tête <wchar.h>
(1)
wchar_t * wcsncpy ( wchar_t * dest, const wchar_t * src, size_t count ) ;
(depuis C95)
(jusqu'à C99)
wchar_t * wcsncpy ( wchar_t * restrict dest, const wchar_t * restrict src, size_t count ) ;
(depuis C99)
errno_t wcsncpy_s ( wchar_t * restrict dest, rsize_t destsz,
const wchar_t * restrict src, rsize_t count ) ;
(2) (depuis C11)
1) Copie au plus count caractères de la chaîne large pointée par src (y compris le caractère large nul de fin) dans le tableau de caractères large pointé par dest .
Si count est atteint avant que la chaîne entière src ne soit copiée, le tableau de caractères larges résultant n'est pas terminé par un caractère nul.
Si, après avoir copié le caractère large nul de terminaison depuis src , count n'est pas atteint, des caractères larges nuls supplémentaires sont écrits dans dest jusqu'à ce qu'un total de count caractères aient été écrits.
Si les chaînes se chevauchent, le comportement est indéfini.
2) Identique à (1) , sauf que la fonction ne continue pas à écrire des zéros dans le tableau de destination pour compléter jusqu'à count , elle s'arrête après avoir écrit le caractère nul de terminaison (s'il n'y avait pas de nul dans la source, elle en écrit un à dest [ count ] puis s'arrête). De plus, les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contraintes actuellement installée :
  • src ou dest est un pointeur nul
  • destsz ou count est zéro ou supérieur à RSIZE_MAX / sizeof ( wchar_t )
  • count est supérieur ou égal à destsz , mais destsz est inférieur ou égal à wcsnlen_s ( src, count ) , en d'autres termes, une troncation se produirait
  • un chevauchement se produirait entre les chaînes source et destination
Comme pour toutes les fonctions à vérification de limites, wcsncpy_s n'est garantie d'être disponible que si __STDC_LIB_EXT1__ est défini par l'implémentation et si l'utilisateur définit __STDC_WANT_LIB_EXT1__ à la constante entière 1 avant d'inclure <wchar.h> .

Table des matières

Paramètres

dest - pointeur vers le tableau de caractères larges à copier
src - pointeur vers la chaîne large à copier
count - nombre maximum de caractères larges à copier
destsz - taille du tampon de destination

Valeur de retour

1) renvoie une copie de dest
2) retourne zéro en cas de succès, retourne une valeur non nulle en cas d'erreur. De plus, en cas d'erreur, écrit L ' \0 ' dans dest [ 0 ] (sauf si dest est un pointeur nul ou destsz est zéro ou supérieur à RSIZE_MAX / sizeof ( wchar_t ) ) et peut altérer le reste du tableau de destination avec des valeurs non spécifiées.

Notes

Dans un usage typique, count est le nombre d'éléments dans le tableau de destination.

Bien que la troncation pour s'adapter au tampon de destination soit un risque de sécurité et donc une violation des contraintes d'exécution pour wcsncpy_s , il est possible d'obtenir le comportement de troncation en spécifiant count égal à la taille du tableau de destination moins un : cela copiera les premiers count caractères larges et ajoutera toujours le terminateur nul large : wcsncpy_s ( dst, sizeof dst / sizeof * dst, src, ( sizeof dst / sizeof * dst ) - 1 ) ;

Exemple

Exécuter ce code 
#include <stdio.h>
#include <wchar.h>
#include <locale.h>
int main(void)
{
    const wchar_t src[] = L"わゐ";
    wchar_t dest[6] = {L'あ', L'い', L'う', L'え', L'お'};
    wcsncpy(dest, src, 4); // this will copy わゐ and repeat L'\0' two times
    puts("The contents of dest are: ");
    setlocale(LC_ALL, "en_US.utf8");
    const long dest_size = sizeof dest / sizeof *dest;
    for(wchar_t* p = dest; p-dest != dest_size; ++p) {
        *p ? printf("%lc ", *p)
           : printf("\\0 ");
    }
}

Sortie possible : 

The contents of dest are: 
わ ゐ \0 \0 お \0

Références

  • Norme C17 (ISO/CEI 9899:2018) :
  • 7.29.4.2.2 La fonction wcsncpy (p: 314)
  • K.3.9.2.1.2 La fonction wcsncpy_s (p: 464)
  • Norme C11 (ISO/CEI 9899:2011) :
  • 7.29.4.2.2 La fonction wcsncpy (p: 431)
  • K.3.9.2.1.2 La fonction wcsncpy_s (p: 640-641)
  • Norme C99 (ISO/IEC 9899:1999) :
  • 7.24.4.2.2 La fonction wcsncpy (p: 377)

Voir aussi

(C95) (C11)
copie une chaîne large vers une autre
(fonction)
(C95) (C11)
copie un certain nombre de caractères larges entre deux tableaux non chevauchants
(fonction)
(C11)
copie un certain nombre de caractères d'une chaîne à une autre
(fonction)
Documentation C++ pour wcsncpy