by Hippo2000(2001/2/26)
原本の著作権はMartien Verbruggen 氏がお持ちです（詳しくは著作権情報を見てください）。Martien Verbruggen 氏からは、メールで了解をいただきました。Thank you, Mr Verbruggen!
内容等が間違っていたら修正します。ご連絡ください。
GD::Graph::Data - GD::Graphのためのデータセットのカプセル化
use GD::Graph::Data;
このモジュールはGD::Graphとその関連で必要とされるデータ構造をカプセル化します。このクラスのオブジェクトはX値のリストを１つ持ち、対応するY値のリストをいくつか持ちます。これはＹ値が数値であるときにだけ意味があります。しかし基本的には何でも格納することができます。未定義値はGD::Graphにとって特別な意味を持ちます。そのためソートされるときには注意して扱われます。
このモジュールのメソッドの多くはGD::Graphとこのモジュールそのものによって内部的に使われるようになっています。あなたにとって便利ではないでしょう。多くは便利であるようにさえ見えません。
use GD::Graph::Data; use GD::Graph::bars;
my $data = GD::Graph::Data->new();
$data->read(file => '/data/sales.dat', delimiter => ','); $data = $data->copy(wanted => [2, 4, 5]);
# データベースから新しい数値を追加します use DBI; # データベースに接続したり、ステートメントを準備し、実行するなどの # DBIのことをします。
while (@row = $sth->fetchrow_array)
{
$data->add_point(@row);
}
my $chart = GD::Graph::bars->new(); my $gd = $chart->plot($data);
またはレガシー・コードに素早く変更するために
# このような配列を組み立てるレガシー・コード @data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4, 3], [6, 3, 7] );
# そして早くそれに対する何らかの操作をおこなう必要とします my $data = GD::Graph::Data->new(); $data->copy_from(\@data);
# そしてやりたかったnewをおこないます
while (@foo = bar_baz())
{
$data->add_point(@foo);
}
新しいGD::Graph::Dataオブジェクトを作成します。
ポイント$np のX値を $valueに設定します。ポイントは0始まりで番号付けされます。おそらくこれは必要としないでしょう。失敗するとundefを返します。
ポイント$npのX値を取得します。set_xをご覧ください。
データセット$ndのポイント$npのY値を$valueに設定します。ポイントは0始まりで、データソットは1始まりで番号付けされます。おそらくこれは必要としないでしょう。失敗するとundefを返します。
データセット$ndのポイント$npのY値を取得します。set_yをご覧ください。エラーのときにはundefを返します。しかしundefを返したからといって、そこにエラーがあるとは限りません。（というのもudef値も格納でき、それが返されたかもしれません）。
データセット$ndのポイント$npの集積されたY値を取得します。集積された値はデータセット 1から$ndまでのポイント$npのすべての値を加算することによって得られます。
x値の最小値と最大値のリストを返します。失敗すると空リストを返します。
データセット$ndでのy値の最小値と最大値のリストを返します。失敗すると空リストを返します。
全てのデータセットでのy値の最小値と最大値のリストを返します。失敗すると空リストを返します。
データセットにポイントを追加します。追加の基本は現在のX値です。つまり以下のような内容のデータセットを持っているとき
(X1, X2) (Y11, Y12) (Y21) (Y31, Y32, Y33, Y34)
$data->add_point(Xx, Y1x, Y2x, Y3x, Y4x) は以下のような結果になります。
(X1, X2, Xx ) (Y11, Y12, Y1x) (Y21, undef, Y2x) (Y31, Y32, Y3x, Y34) (undef, undef, Y4x)
言いかえれば：使い方に注意してください。注意している限り、すべてのデータセットは同じ長さになり、このメソッドは安全です。
データセットの数を返します。
リスト・コンテキストでは、最初の要素はX値の数、そして後の要素はそれおぞれのデータセットのY値の数が入ったリストを返します。スカラ・コンテキストではX値セットを持っているポイントの数を返します。つまりmake_strictの呼び出し結果になるであろうデータセットの数です。
すべてのX値のリストを返します。
データセット$ndのためのY値のリストを返します。データセットは1始まりで番号付けされます。$ndが範囲外であるか、$ndがからであれば、空リストを返します。
オブジェクト・メソッドの場合：データ・コンテナをリセットし、すべてのデータとエラーメッセージを除去します。クラス・メソッドの場合：蓄積されたエラーメッセージと可能な限り他の凝りを除去します。
すべてのデータセットに長すぎるデータセットは切り捨てて、短すぎるデータセットにはundefを埋めることによりXリストと同じ長さのリストにさせます。常にtrueを返します。
cumulate パラメータは以下のようにY値セットを集計します：最初のY値リストは変更されません。2番目は最初と２番目の合計が入ります。３番目には最初と2番目と3番目の合計がといった具合です。失敗するとundefを返します。
もし引数preserve_undef がtrueに設定されていると、全く未定義値だけの合計は未定義値のままになります。もしそれがないか、false値であれば、undefは0として扱われます。最初のデータの未定義値はそのままであることに注意してください。
注意：Y値に数値でないものに定義されていれば、0として扱われます。しかし本当はそのようなものをYデータに格納してこれを使うべきではありません。
引数リストに入っているものを除いてすべてのデータセットを削除します。これは与えられた順番にデータセットを並べ替えもします。失敗するとundefを返します。
最初、6番目、2番目以外のデータセットを削除し、その順番にしたければ以下のようにします：
$data->wanted(1, 6, 2) or die $data->error;
データセットの順番を逆にします。
'古い'形式のGD::Graphデータ構造または他のGD::Graph::Dataオブジェクトをこのオブジェクトにコピーします。これは現在のデータを削除します。失敗するとundefを返します。
オブジェクトのコピーを返します。失敗するとundefを返します。
ファイルからデータセットを読み込みます。これは現在のデータを削除します。失敗するとundefを返します。このメソッドは行を解析するために標準モジュールText::ParseWordsを使います。もしなんらかの奇妙な理由でこれを持っていないのであれば、このメソッドは使わないで下さい。でないとプログラムは死にます(die)。
データファイル・フォーマット: デフォルトのデータファイル・フォーマットはタブ区切りのデータです（これはdelimiter引数によって変更することができます）。コメント行は#で始まるすべての行です。以下の例ではわかりやすくするため、リテラルのタブを<tab>に置換えています。
# これはコメントで、無視されます。 Jan<tab>12<tab>24 Feb<tab>13<tab>37 # March is missing Mar<tab><tab> Apr<tab>9<tab>18
適切な引数は以下の通り：
file, 必須。読み込むファイル名：
$data->read(file => '/data/foo.dat') or die $data->error;
no_comment, オプション。最初が#である行を飛ばしたくないとき、これをtrueにしてください。
$data->read(file => '/data/foo.dat', no_comment => 1);
delimiter, オプション。１つのタブの代わりに区切り文字となる正規表現。
$data->read(file => '/data/foo.dat', delimiter => '\s+'); $data->read(file => '/data/foo.dat', delimiter => qr/\s+/);
現在のオブジェクトに集積されたすべてのエラーを返します。スカラ・コンテキストでは最後のエラーを返します。クラス・メソッドとして呼ばれると、クラス・レベルで機能します。
このメソッドは継承されています。詳しくはGD::Graph::Error をご覧ください。
そのオブジェクト（あるいはクラス）がエラーを保留していればtrueを返し、そうでなければfalseを返します。場合によっては（copyをご覧ください）、これがエラーをチェックする一番よい方法です。
このメソッドは継承されています。詳しくはGD::Graph::Error をご覧ください。
すべてのPerlためのモジュールに：インタフェースを守って使うようにしてください。このモジュールの内部の知識を使ってもて遊びすぎると痛い目にあうでしょう。いつかはこれを変更するかもしれません。特におそらくこれを配列リファレンスとして実装しつづけないでしょう。
Martien Verbruggen <mgjv@comdyn.com.au>
Copyright (c) 2000 Martien Verbruggen.
All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。