Sous-routine regexec

Objectif

Compare la chaîne de caractères à terminaison nulle spécifiée par la valeur du paramètre String à l'expression rationnelle compilée Preg, qui doit avoir été compilée au préalable par un appel à la sous-routine 'regcomp

Bibliothèque

Bibliothèque C standard (libc. a)

Syntaxe

#include <regex.h>

int regexec (Preg, String, NMatch, PMatch, EFlags)
const regex_t * Preg;
const char * String;
size_t  NMatch;
regmatch_t * PMatch;
int  EFlags;

Descriptif

La sous-routine " regexec compare la chaîne de caractères à terminaison nulle du paramètre " String" avec l'expression rationnelle compilée, basique ou étendue, du paramètre " Preg ", initialisée par un appel précédent à la sous-routine " regcomp. Si une correspondance est trouvée, la sous-routine " regexec renvoie la valeur 0. La sous-routine " regexec renvoie une valeur non nulle si elle ne trouve pas de correspondance ou si elle trouve une erreur.

Si le paramètre NMatch a une valeur de 0, ou si l'indicateur " REG_NOSUB a été activé lors de l'appel à la sous-routine " regcomp, la sous-routine " regexec ignore le paramètre PMatch. Sinon, le paramètre Sittelle pointe vers un tableau d'au moins le nombre d'éléments spécifiés par le paramètre NMatch . La sous-routine " regexec remplit les éléments du tableau indiqué par le paramètre PMatch avec les décalages des sous-chaînes du paramètre String. Les décalages correspondent aux sous-expressions parenthétiques du paramètre de motif original qui a été spécifié à la sous-routine " regcomp

La structure " pmatch.rm_so est le décalage d'octets du début de la sous-chaîne et la structure " pmatch.rm_eo est supérieure d'une unité au décalage d'octets de la fin de la sous-chaîne. La sous-expression I commence à la I e parenthèse ouvrque correspondante, en comptant à partir de 1. L'élément 0 du tableau correspond à l'ensemble du modèle. Les éléments inutilisés du paramètre PMatch, jusqu'à la valeur PMatch[NMatch -1], sont complétés par -1. If more than the number of subexpressions are specified by the NMatch parameter (the modèle parameter itself counts as a subexpression), only the first NMatch -1 subexpressions are recorded.

Lorsqu'une expression régulière de base ou étendue est mise en correspondance, une sous-expression entre parenthèses donnée du paramètre Modèle peut correspondre à plusieurs sous-chaînes différentes du paramètre Chaîne . Sinon, il se peut qu'il ne corresponde à aucune sous-chaîne même si le modèle dans son ensemble correspond.

Les règles suivantes sont utilisées pour déterminer les sous-chaînes à déclarer dans le paramètre Sittelle lorsque des expressions régulières sont associées:

Si une sous-expression d'une expression régulière a participé plusieurs fois à la correspondance, le décalage de la dernière sous-expression correspondante est indiqué dans le paramètre PMatch.
Si une sous-expression n'a pas participé à une correspondance, le décalage d'octet dans le paramètre PMatch est une valeur de -1 Une sous-expression ne participe pas à une correspondance si l'une des suivantes est vraie:
- Un " * (astérisque) ou un " \{\} (barre oblique inverse, accolade gauche, barre oblique inverse, accolade droite) apparaît immédiatement après la sous-expression dans une expression régulière de base.
- Un " * (asterisk), ? (question mark), ou un " { } (accolades à gauche et à droite) apparaît immédiatement après la sous-expression dans une expression rationnelle étendue et la sous-expression ne correspond pas (correspond à 0 fois).
- Un " | (pipe) est utilisé dans une expression rationnelle étendue pour sélectionner soit la sous-expression qui ne correspond pas, soit une autre sous-expression, et l'autre sous-expression correspond.
Si une sous-expression est contenue dans une autre sous-expression, les données du paramètre PMatch se réfèrent à la dernière sous-expression.
Si une sous-expression est contenue dans une sous-expression et que les décalages d'octets dans le paramètre PMatch ont une valeur de -1, les pointeurs dans le paramètre PMatch ont également une valeur de -1.
Si une sous-expression correspond à une chaîne de longueur nulle, les décalages dans le paramètre PMatch se réfèrent à l'octet qui suit immédiatement la chaîne correspondante.

Si l'indicateur " REG_NOSUB a été défini dans le paramètre cflags lors de l'appel à la sous-routine " regcomp " et que le paramètre NMatch n'est pas égal à 0 lors de l'appel à la sous-routine " regexec ", le contenu du tableau PMatch n'est pas spécifié.

Si l'indicateur " REG_NEWLINE n'a pas été défini dans le paramètre cflags lors de l'appel de la sous-routine " regcomp, un caractère de nouvelle ligne dans le motif ou le paramètre String est traité comme un caractère ordinaire. Si l'indicateur " REG_NEWLINE a été activé lors de l'appel de la sous-routine " regcomp, le caractère de nouvelle ligne est traité comme un caractère ordinaire, sauf dans les cas suivants :

Un caractère de nouvelle ligne dans le paramètre Chaîne n'est pas compensé par un point en dehors d'une expression entre crochets ou par une forme quelconque de liste de non-correspondance. Une expression de liste non concordante commence par ^ (circonflexe) et spécifie une liste qui correspond à n'importe quel caractère ou élément de classement et à l'expression dans la liste après le caret de premier plan. Par exemple, l'expression régulière " [^abc] correspond à tous les caractères sauf " a, " b ou " c. L'accent circonflexe n'a cette signification particulière que lorsqu'il est le premier caractère de la liste, immédiatement après le crochet gauche.
Un " ^ (accent circonflexe) dans le paramètre " pattern", lorsqu'il est utilisé pour spécifier l'ancrage d'une expression, correspond à la chaîne de longueur zéro située immédiatement après un caractère de nouvelle ligne dans le paramètre " String", quel que soit le réglage de l'indicateur " REG_NOTBOL
Un " $ (signe de dollar) dans le paramètre " pattern", lorsqu'il est utilisé pour spécifier l'ancrage d'une expression, correspond à la chaîne de longueur zéro immédiatement avant un caractère de nouvelle ligne dans le paramètre " String", quelle que soit la valeur de l'indicateur " REG_NOTEOL

Paramètres

Tableau 1. Paramètres
Article	Descriptif
`Prég`	Contient l'expression régulière de base ou étendue compilée à comparer au paramètre `Chaîne` .
`Chaîne`	Contient les données à correspondre.
`NMatch`	Contient le nombre de sous-expressions à mettre en correspondance.
`Sittelle`	Contient le tableau de décalage dans le paramètre `Chaîne` qui correspond à la sous-expression correspondante dans le paramètre `Prég` .
`Indicateurs`	Contient le OU inclusif dans le sens des bits de 0 ou plus des drapeaux contrôlant le comportement du sous-programme " regexec pouvant être personnalisé. Le paramètre `Indicateurs` modifie l'interprétation du contenu du paramètre `Chaîne` . Il s'agit du OU inclusif dans le sens des bits de 0 ou plusieurs des drapeaux suivants, qui sont définis dans le fichier " regex.h: `REG_NOTBOL` Le premier caractère de la chaîne pointé par le paramètre `Chaîne` n'est pas le début de la ligne. Par conséquent, le " `^` (accent circonflexe), lorsqu'il est utilisé comme caractère spécial, ne correspond pas au début du paramètre `"chaîne"`. `REG_NOTEOL` Le dernier caractère de la chaîne pointé par le paramètre `Chaîne` n'est pas la fin de la ligne. Par conséquent, le " `$` " (signe du dollar), lorsqu'il est utilisé comme caractère spécial, ne correspond pas à la fin du paramètre `"chaîne"`.

Valeurs renvoyées

En cas de succès, le sous-programme " regexec renvoie la valeur 0 pour indiquer que le contenu du paramètre " chaîne" correspond au contenu du paramètre " motif", ou pour indiquer qu'il n'y a pas eu de correspondance. L'erreur " REG_NOMATCH est définie dans le fichier " regex.h

Codes d'erreur

Si la sous-routine " regexec échoue, elle renvoie une valeur non nulle indiquant le type de problème. Les macros suivantes pour les codes d'erreur possibles qui peuvent être renvoyés sont définies dans le fichier " regex.h:

Tableau 2. Codes d'erreur
Article	Descriptif
`REG_NOMATCH`	Indique que l'expression régulière de base ou étendue n'a pas pu trouver de correspondance.
`REG_BADPAT`	Indique une expression régulière de base ou étendue qui n'est pas valide.
`REG_ECOLLATE`	Indique un élément de classement référencé qui n'est pas valide.
`REG_ECTYPE`	Indique une référence de type de classe de caractères non valide.
`REG_EESCAPE`	Indique la présence d'un " `\` (barre oblique inverse) dans le motif.
`REG_ESUBREG`	Indique qu'un nombre dans '`\digit` n'est pas valide ou est en erreur.
`REG_EBRACK`	Indique un déséquilibre " `[ ]` (parenthèses gauche et droite).
`REG_EPAREN`	Indique un déséquilibre `\ ( \ )` (barre oblique inverse, parenthèse gauche, barre oblique inverse, parenthèse droite) ou ( ) (parenthèses gauche et droite).
`REG_EBRACE`	Indique un déséquilibre " `\ { \ }` (barre oblique inversée, accolade gauche, barre oblique inversée, accolade droite).
`REG_BADBR`	Indique que le contenu de " `\ { \ }` (barre oblique inverse, accolade gauche, barre oblique inverse, accolade droite) est inutilisable (pas un nombre, nombre trop grand, plus de deux nombres, ou premier nombre plus grand que le second).
`REG_ERANGE`	Indique un point final inutilisable dans une expression de plage.
`REG_ESPACE`	Indique que la mémoire est en mémoire.
`REG_BADRPT`	Indique " `a ?` (point d'interrogation), * (astérisque) ou + (signe plus) non précédé d'une expression régulière de base ou étendue valide.

Si la valeur du paramètre Preg de la sous-routine " regexec n'est pas une expression rationnelle compilée, de base ou étendue, renvoyée par la sous-routine " regcomp, le résultat est indéfini.

Exemples

L'exemple suivant montre comment l'indicateur 'REG_NOTBOL peut être utilisé avec la sous-routine 'regexec pour trouver toutes les sous-chaînes d'une ligne qui correspondent à un motif fourni par l'utilisateur. (Pour des raisons de simplicité, peu de contrôles d'erreurs sont effectués dans cet exemple)

(void) regcomp (&re, pattern, 0) ;
/* this call to regexec finds the first match on the line */
error = regexec (&re, &buffer[0], 1, &pm, 0) ;
while (error = = 0) {   /* while matches found */
<subString found between pm.r._sp and pm.rm_ep>
/* This call to regexec finds the next match */
error = regexec (&re, pm.rm_ep, 1, &pm, REG_NOTBOL) ;