<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2013 - Samuel GOUGEON
 * Copyright (C) 2009 - Université du Maine - Samuel GOUGEON
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="members" xml:lang="ja">
    <refnamediv>
        <refname>members</refname>
        <refpurpose>
            配列の各要素または他の配列の行または列を数える(及び位置を調べる)
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>呼び出し手順</title>
        <synopsis>
            [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")
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>引数</title>
        <variablelist>
            <varlistentry>
                <term>N</term>
                <listitem>
                    <para>
                        Needles: 論理値, 整数エンコードされた数値, 実数または複素数の10進数, 多項式またはテキストの行列またはハイパー行列.
                        "rows"または"cols"モードでは,
                        ハイパー行列は指定できません.
                        指定した値(または行または列)は<literal>N</literal>の中に
                        複数回配置することができます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>H</term>
                <listitem>
                    <para>
                        Haystack:
                        <literal>N</literal>と同じデータ型の行列またはハイパー行列.
                        "rows" または "cols" モードの場合, ハイパー行列は指定できません.
                        <literal>N</literal> および <literal>H</literal>
                        はそれぞれ同じ列または行の数を有する必要があります.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>オプション:</term>
                <listitem>
                    <para>以下の1から3個のオプションを順を問わず指定可能です:
                        <variablelist>
                            <varlistentry>
                                <term>"last"</term>
                                <listitem>
                                    <para>
                                        <literal>N</literal>から
                                        needlesの<literal>H</literal>の位置を<literal>loc</literal>で
                                        検索した場合,
                                        デフォルトで<literal>H</literal>の中でそれぞれが最初に現れる位置が返されます.
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>"rows", "cols"</term>
                                <listitem>
                                    <para>
                                        デフォルトで, <literal>N</literal>の各要素<literal>N(i, j, ...)</literal>
                                        は <literal>H</literal>の中で検索する際のneedleとみなされます.
                                        <literal>"rows"</literal> が検索された場合,
                                        <literal>N</literal>の各行はneedleとみなされ, 全体として,
                                        <literal>H</literal>の行で検索が行われます.
                                        <literal>"cols"</literal> が使用された場合,
                                        <literal>"cols"</literal>が
                                        <literal>N</literal> 及び <literal>H</literal>の列に適用されます.
                                        <literal>"cols"</literal> を使用した場合,
                                        <literal>N</literal> 及び <literal>H</literal> の列数と同じ部分に
                                        適用されます.
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>"shuffle"</term>
                                <listitem>
                                    <para>
                                        <literal>"rows"</literal>または<literal>"cols"</literal> モードの場合,
                                        行/列の要素のデフォルトの順序が考慮されます: 例えば,<literal>N</literal>
                                        の <literal>[ 7 3 5 ]</literal> は,
                                        <literal>H</literal>の<literal>[3 5 7]</literal>にマッチしません.
                                        <literal>"shuffle"</literal> が指定された場合,
                                        例えば<literal>[3 5 7]</literal>の交換は
                                        <literal>N</literal>の<literal>[3 5 7]</literal>行に一致すると
                                        みなされます.
                                        このオプションは多項式の場合,無視されます.
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nb</term>
                <listitem>
                    <para>
                        通常モードの場合: <literal>nb(i, j, ...)</literal> は(実数として)
                        <literal>H</literal>における<literal>N(i, j, ...)</literal>の出現回数
                        を表します.
                        <literal>nb</literal> および <literal>N</literal> は同じ形式です.
                        <literal>H</literal> が空の場合, ゼロ行列が返されます.
                        <literal>N</literal> が空の場合, 空の行列 <literal>[]</literal> が返されます.
                    </para>
                    <para>
                        <literal>"rows"</literal> または <literal>"cols"</literal> モードの場合:
                        <literal>nb</literal> は <literal>N</literal> が有する行/列と同じ数の要素を
                        有する実数の行です.
                        <literal>nb(i)</literal> は,<literal>H(., :)</literal> の中で
                        <literal>N(i, :)</literal> が生じた数
                        (または<literal>H(:, .)</literal>の中で<literal>N(:, i)</literal>)を返します.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>loc</term>
                <listitem>
                    <para>
                        通常のモードの場合:
                        <literal>loc</literal> および<literal>N</literal> は同じ形式を有します.
                        <literal>loc(i, j, ...)</literal> は,
                        <literal>N(i, j, ...)</literal> がある場所として
                        <literal>H</literal>に最小の線形化された添字を返します.
                        <literal>"last"</literal>フラグが使用された場合,
                        替りに最大の線形化された添字の最大値が返されます.
                        <literal>H</literal>の中に <literal>N(i, j, ...)</literal>が見つかれない場合,
                        <literal>loc(i, j, ...)</literal> は <literal>0</literal>に設定されます.
                    </para>
                    <para>
                        <literal>"rows"</literal> または <literal>"cols"</literal> モードの場合:
                        <literal>loc</literal> は<literal>N</literal>が有する行及び列と同じ
                        数の要素を有する実数の行です.
                        <literal>loc(i)</literal> は,
                        <literal>N(i, :)</literal>に一致する最初の
                        行<literal>H(loc(i), :)</literal>の添字
                        (または <literal>N(:, i)</literal>に一致する最初の列
                        <literal>H(:, loc(i))</literal> の添字)を返します.
                        <literal>"shuffle"</literal>フラグが追加で指定された場合,
                        行/列に基づく要素の順番は考慮されません.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>説明</title>
        <para>
            <literal>nb = members(N, H [,"rows"|"cols"])</literal>
            は各要素または<literal>H</literal>の中にある
            <literal>N</literal>の行または列の発生回数を返します.
            要素が見つからない場合, 0 が返されます.
            <literal>N(i,j,...)</literal>が現れる最初(デフォルト)または
            <literal>"last"</literal>(最後)の<literal>H</literal>の添字を,
            2番目のオプションの出力<literal>loc</literal>により取得できます.
            <literal>"rows"</literal> または <literal>"cols"</literal>
            の一致するものを探す場合,
            オプション<literal>"shuffle"</literal>を使用することにより,
            一致の際の要素の順番を無視することができます.
        </para>
        <para>
            値 <literal>%inf</literal> および <literal>-%inf</literal>
            を<literal>N</literal>の中および<literal>H</literal>の中で
            使用することができます.
            ノーマルモードでは,
            <literal>%nan</literal>が<literal>N</literal>の中では
            サポートされますが,<literal>H</literal>の中ではサポートされません.
            <literal>"rows"</literal> または <literal>"cols"</literal> モードの場合,
            <literal>%nan</literal> はどこでもサポートされます.
        </para>
        <para>
            通常の要素毎のモードの場合, members(..) は,
            論理値,
            整数エンコードされた数値(8-16-32ビット長の符号ありまたは無し)
            および実数を高速に処理するために
            <link linkend="dsearch">dsearch(..)</link> を使用します.
            計算時間が長い場合, 進行状況の棒グラフが表示されます.
        </para>
    </refsection>
    <refsection>
        <title>例</title>
        <programlisting role="example"><![CDATA[
N = [1 8 4 5 2 1];
H = [9 7 4 2 1 4];

[nb, loc] = members(N, H, "last")
// nb  = [1 0 2 0 1 1] を返す: 例えば, Hの中に4が2回現れる.
// そして loc = [5 0 6 0 4 5]: 4が最後に現れるのはHの6番目の位置

[nb, loc] = members(N, H)
// loc = [5 0 3 0 4 5]を返す: 4が最初に現れるのはHの3番目の位置

// ハイパー行列の場合. 前記の N 及び Hを利用:
N = matrix(N, [3 1 2]);
H = matrix(H, [3 1 2]);
[nb, loc] = members(N, H, "last")

// 整数の場合:
N = int8(grand(3, 2, "uin", -5, 5));
H = int8(grand(4, 4, "uin", -5, 5));
[nb, loc] = members(N, H)

// 多項式の場合 (複素数の係数を指定可能):
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)

// テキストの場合:
N = [ "Hi" "Hu" "Allo"];
H = [ "Hello" "Bonjour" "Allo"
      "Holà"  "Allo"  "Hallo"
      "Hi"    "Hé"    "Salud" ];
[nb, loc] = members(N, H, "last")

// 行の場合:
 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] 及び [0 4 1] は同一とみなされる

 // 列の場合: 定義済みの N 及び H を利用:
 N = N.', H = H.'
 [nb, loc] = members(N, H, "cols", "shuffle")
]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>参照</title>
        <simplelist type="inline">
            <member>
                <link linkend="dsearch">dsearch</link>
            </member>
            <member>
                <link linkend="intersect">intersect</link>
            </member>
            <member>
                <link linkend="grep">grep</link>
            </member>
            <member>
                <link linkend="find">find</link>
            </member>
            <member>
                <link linkend="vectorfind">vectorfind</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>履歴</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>members() 関数が導入されました.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
