FoldStringW, fonction (stringapiset.h)

Mappe une chaîne Unicode à une autre, en effectuant la transformation spécifiée. Pour obtenir une vue d’ensemble de l’utilisation des fonctions de chaîne, consultez Chaînes.

Syntaxe

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Paramètres

[in] dwMapFlags

Indicateurs spécifiant le type de transformation à utiliser pendant le mappage de chaînes. Ce paramètre peut être une combinaison des valeurs suivantes.

[in] lpSrcStr

Pointeur vers une chaîne source que la fonction mappe.

[in] cchSrc

Taille, en caractères, de la chaîne source indiquée par lpSrcStr, à l’exclusion du caractère null de fin. L’application peut définir le paramètre sur n’importe quelle valeur négative pour spécifier que la chaîne source se termine par un caractère Null. Dans ce cas, la fonction calcule automatiquement la longueur de chaîne et termine la chaîne mappée indiquée par lpDestStr.

[out, optional] lpDestStr

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère la chaîne mappée.

[in] cchDest

Taille, en caractères, de la chaîne de destination indiquée par lpDestStr. Si l’espace d’un caractère null de fin est inclus dans cchSrc, cchDest doit également inclure de l’espace pour un caractère null de fin.

L’application peut définir cchDest sur 0. Dans ce cas, la fonction n’utilise pas le paramètre lpDestStr et retourne la taille de mémoire tampon requise pour la chaîne mappée. Si l’indicateur MAP_FOLDDIGITS est spécifié, la valeur de retour correspond à la taille maximale requise, même si le nombre réel de caractères requis est inférieur à la taille maximale. Si la taille maximale n’est pas passée, la fonction échoue avec ERROR_INSUFFICIENT_BUFFER.

Valeur retournée

Retourne le nombre de caractères dans la chaîne traduite, y compris un caractère null de fin, en cas de réussite. Si la fonction réussit et que la valeur de cchDest est 0, la valeur de retour correspond à la taille de la mémoire tampon requise pour contenir la chaîne traduite, y compris un caractère null de fin.

Cette fonction retourne 0 si elle ne réussit pas. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

• ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas suffisamment grande ou a été incorrectement définie sur NULL.
• ERROR_INVALID_DATA. Les données n’étaient pas valides.
• ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
• ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.
• ERROR_MOD_NOT_FOUND. Le module est introuvable.
• ERROR_OUTOFMEMORY. L’espace de stockage disponible n’était pas suffisant pour effectuer cette opération.
• ERROR_PROC_NOT_FOUND. La procédure requise est introuvable.

Remarques

Les valeurs des paramètres lpSrcStr et lpDestStr ne doivent pas être identiques. Si elles sont identiques, la fonction échoue avec ERROR_INVALID_PARAMETER.

La zone de compatibilité dans Unicode se compose de caractères de la plage 0xF900 par 0xFFEF qui sont affectés à des caractères d’autres normes d’encodage pour les caractères, mais qui sont en fait des variantes de caractères déjà dans Unicode. La zone de compatibilité est utilisée pour prendre en charge le mappage aller-retour à ces normes. Les applications peuvent utiliser l’indicateur MAP_FOLDCZONE pour éviter la prise en charge de la duplication de caractères dans la zone de compatibilité.

À compter de Windows Vista : Cette fonction prend en charge la normalisation Unicode. Tous les caractères de compatibilité Unicode sont mappés.

À compter de Windows Vista : Les transformations indiquées par les indicateurs MAP_FOLDCZONE, MAP_PRECOMPOSED et MAP_COMPOSITE utilisent les formulaires de normalisation Unicode KC, C et D (via la fonction NormalizeString ) pour effectuer les mappages.

À compter de Windows 8 : la version ANSI de la fonction est déclarée dans Winnls.h et la version Unicode est déclarée dans Stringapiset.h. Avant Windows 8, les deux versions étaient déclarées dans Winnls.h.

Configuration requise

Voir aussi

Prise en charge des langues nationales

Fonctions de prise en charge des langues nationales

NormalizeString

Considérations relatives à la sécurité : Fonctionnalités internationales

Tri

Utilisation de la normalisation Unicode pour représenter des chaînes