Sous-routine wcsrtombs ou wcsnrtombs

Objectif

Convertir une chaîne de caractères larges en chaîne de caractères (réitérable).

Bibliothèque

Bibliothèque standard (libc.a)

Syntaxe

#include <wchar.h>

size_t wcsrtombs (char * dst, const wchar_t ** src, size_t len, mbstate_t * ps);
size_t wcsnrtombs (char * dst, const wchar_t ** src, size_t nwc, size_t len, mbstate_t * ps);

Descriptif

La fonction Wcsrtombes convertit une séquence de caractères larges à partir du tableau indirectement pointé par Src dans une séquence de caractères correspondants, à partir de l'état de conversion décrit par l'objet désigné par Ps.Si Dst n'est pas un pointeur null, les caractères convertis sont alors stockés dans le tableau désigné par Dst. La conversion continue jusqu'à et inclut un caractère de largeur nulle de fin, qui est également stocké. La conversion s'arrête plus tôt dans les cas suivants:

• Lorsqu'un code est atteint, il ne correspond pas à un caractère valide.
• Lorsque le caractère suivant dépasserait la limite du nombre total d'octets Len à stocker dans le tableau désigné par Dst (et Dst n'est pas un pointeur null).

Chaque conversion a lieu comme s'il s'agit d'un appel à la fonction Wcrtombeau .

Si Dst n'est pas un pointeur null, l'objet pointeur pointant vers Src est affecté soit à un pointeur nul (si la conversion est arrêtée en raison d'un caractère de fin de largeur nulle) ou à l'adresse qui vient d'être convertie (le cas échéant). Si la conversion s'est arrêtée en raison d'un caractère de fin de largeur nulle, l'état qui en résulte est l'état de conversion initial.

Si ps est un pointeur null, la fonction Wcsrtombes utilise son propre objet interne Mbstate_t , qui est initialisé au démarrage du programme jusqu'à l'état de conversion initial. Sinon, l'objet Mbstate_t désigné par Ps est utilisé pour décrire complètement l'état de conversion en cours de la séquence de caractères associée. L'implémentation se comportera comme si aucune fonction définie dans cette spécification appelle Wcsrtombes.

La fonction Wcsnrtombes est équivalente à la fonction Wcsrtombes , sauf que la conversion est limitée aux premiers caractères Nwc .

Le comportement de cette fonction est affecté par la catégorie LC_CTYPE de l'environnement local en cours.

Valeurs renvoyées

Si la conversion s'arrête car un code est atteint qui ne correspond pas à un caractère valide, une erreur de codage se produit. Dans ce cas, les fonctions Wcsrtombes et Wcsnrtombes stockait la valeur de la macro EILSEQ dans Errno et renvoie (size_t) -1; l'état de conversion n'est pas défini. Sinon, les fonctions Wcsrtombes et Wcsnrtombes renvoient le nombre d'octets dans la séquence de caractères obtenue, sans inclure la valeur null de fin (le cas échéant).

Codes d'erreur

La fonction Wcsrtombes peut échouer si: