# members

dénombre (et localise) dans un tableau chaque élément ou ligne ou colonne d'un autre tableau

## Séquence d'appel

                [nb [,loc]] = members(N, H)
                [nb [,loc]] = members(N, H, "last")
                [nb [,loc]] = members(N, H, "rows"|"cols")
                [nb [,loc]] = members(N, H, "rows"|"cols", "last")
                [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle")
                [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle", "last")

## Paramètres

N

  Matrice ou hypermatrice dont les éléments, rangées ou colonnes doivent être recherchés. Il peut s'agir de booléens, d'entiers encodés, de nombres décimaux réels ou complexes, de polynômes ou de textes. En mode "rows" ou "cols", l'hypermatrice n'est pas acceptée. Un élément donné (ou une rangée ou colonne) peut apparaitre plusieurs fois dans `N`.

H

  Matrice ou hypermatrice scrutée, de même type que `N`. En mode "rows" / "cols", l'hypermatrice n'est pas acceptée, et `N` et `H` doivent avoir le même nombre de colonnes / lignes.

Options :

  Une à 3 options peuvent être indiquées après H, sans ordre particulier :

  "last"

    Lorsque la localisation dans `H` des éléments de `N` est retournée via le paramètre de sortie `loc`, par défaut les positions des 1ères occurences dans `H` sont retournées, élément par élément de N. Si `"last"` est indiqué, les positions retournées sont celles des dernières occurences dans `H`.

  "rows", "cols"

    Par défaut, chaque élément individuel `N(i, j, ..)` de `N` est recherché dans `H`. Si `"rows"` est indiquée, chaque rangée de `N` est recherchée parmi les rangées de `H`. De même, si `"cols"` est indiquée, chaque colonne de `N` est recherchée parmi les colonnes de `H.`.

  "shuffle"

    En mode `"rows"` ou `"cols"`, par défaut l'ordre des éléments d'une rangée ou d'une colonne est pris en compte : par exemple, `[ 7 3 5 ]` dans `N` et `[ 3 5 7]` dans `H` ne correspondront pas. Lorsque l'option `"shuffle"` est utilisée, toute permutation de --disons--`[3 5 7]` sera reconnue dans H comme correspondant à la rangée `[3 5 7]` dans `N`. Cette option est ignorée pour les polynômes.

nb

  En mode normal : `nb(i, j, ..)` (décimaux) retourne le nombre d'occurences dans `H` de `N(i, j, ..)`. `nb` et `N` ont le même format. Si `H` est vide [], une matrice de zéros est retournée. Si `N` est vide, la matrice vide `[]` est retournée.

  En mode `"rows"` ou `"cols"` : `nb` est un vecteur ligne de décimaux avec autant d'élements que `N` a de rangées ou colonnes. `nb(i)` retourne le nombre d'occurences dans `H(1:$, :)` de `N(i, :)` (ou de `N(:, i)` dans `H(:, 1:$)` ).

loc

  En mode normal : `loc` et `N` ont le même format. `loc(i, j, ..)` retourne le n°(linéarisé) dans `H` le plus petit auquel `N(i, j, ..)` advient : `H(loc(i, j, ..))==N(i, j, ..)`. Si l'option `"last"` est utilisée, le n° le plus grand vérifiant la même condition est retourné à la place. Si `N(i, j, ..)` n'est pas présent dans `H`, `loc(i, j, ..)` est mis à `0`.

  En mode `"rows"` ou `"cols"` : `loc` est un vecteur ligne de décimaux, avec autant d'éléments que `N` a respectivement de rangées ou de colonnes. `loc(i)` retourne le n° de la 1ère ligne `H(loc(i), :)` identifiable à `N(i, :)` (ou le n° de la 1ère colonne `H(:, loc(i))` identifiable à `N(:, i)`). Si l'option `"shuffle"` est en outre utilisée, l'ordre des éléments de `N(i, :)` est ignoré et toutes les permutations de `N(i, :)` identifiables en rangées de `H` sont considérées.

## Description

`nb = members(N, H [,"rows"|"cols"])` retourne le nombre d'occurences de chaque élément ou rangée ou colonne de `N` identifiables dans `H`. Si aucune correspondance n'est trouvée, 0 est retourné pour le composant considéré. La position dans `H` de la 1ère (par défaut) ou de la dernière (avec `"last"`) occurence des `N(i, j, ...)` peut être obtenue via la seconde variable de sortie `loc`. Si des rangées ou colonnes correspondantes sont recherchées, l'ordre de leurs éléments peut être ignoré en utilisant l'option `"shuffle"`.

Les valeurs spéciales `%inf` et `-%inf` sont admises dans `N` comme dans `H`. `%nan` est toujours admis dans `N`, mais pas dans `H` en mode normal.

En mode normal (élément par élément), members(..) utilise la fonction dsearch(..) afin de traiter efficacement les tableaux de booléens, d'entiers encodés (de tous formats : 8-16-32 bits signés ou non), ou de nombres réels. Le traitement des tableaux de nombres complexes, de polynômes ou de textes est réalisé par un algorithme plus lent et gourmand en mémoire vive. Pour de meilleures performances avec ces types de données, en particulier si `N` ou/et `H` sont de grandes tailles, l'utilisateur peut préalablement augmenter la taille de la pile dévolue aux variables en utilisant stacksize(..). Lorsque le traitement est long, une jauge de progression est affichée.

## Exemples

    N = [1 8 4 5 2 1];
    H = [9 7 4 2 1 4];

    [nb, loc] = members(N, H, "last")
    // Retourne nb  = [1 0 2 0 1 1] : par exemple, 4 apparait 2 fois dans H.
    // Et       loc = [5 0 6 0 4 5] : la dernière occurence de 4 figure en 6ème position dans H

    [nb, loc] = members(N, H)
    // Retourne loc = [5 0 3 0 4 5] : la 1ère occurence de 4 figure en 3ème position dans H

    // avec des hypermatrices. Avec N et H déclarées ci-dessus :
    N = matrix(N, [3 1 2]);
    H = matrix(H, [3 1 2]);
    [nb, loc] = members(N, H, "last")

    // Avec des entiers encodés :
    N = int8(grand(3, 2, "uin", -5, 5));
    H = int8(grand(4, 4, "uin", -5, 5));
    [nb, loc] = members(N, H)

    // Avec des polynômes (à coefficients éventuellement complexes) :
    z = %z;
    N = [z (1-z)^2 ; -4 %i*z ];
    H = [2  %i*z -z  3-z  z  z^3 z];
    [nb, loc] = members(N, H)

    // Avec des matrices de textes :
    N = [ "Hi" "Hu" "Allo"];
    H = [ "Hello" "Bonjour" "Allo"
          "Holà"  "Allo"  "Hallo"
          "Hi"    "Hé"    "Salud" ];
    [nb, loc] = members(N, H, "last")

    // Recherche de rangées :
     H = [
      3  3  0
      4  1  0
      2  0  3
      0  1  4
      3  4  3
      0  4  1
      3  1  0
      ];
     N = [
      1  2  3
      0  1  4
      3  0  3
      4  1  0
      2  0  2
      ];
     N, H
     [nb, loc] = members(N, H, "rows")
     [nb, loc] = members(N, H, "rows","last")
     [nb, loc] = members(N, H, "rows","shuffle") // [4 1 0], [0 1 4] et [0 4 1] sont associées

    // Recherche de colonnes, en utilisant N et H définies ci-dessus :
     N = N.', H = H.'
     [nb, loc] = members(N, H, "cols", "shuffle")

## Voir aussi

- dsearch
- intersect
- find
- vectorfind

## Historique

5.5.0
Introduction de la fonction members()