{ "content": [ { "type": "text", "text": "# GD::Graph::Data (perldoc)\n\n## NAME\n\nGD::Graph::Data - Data set encapsulation for GD::Graph\n\n## SYNOPSIS\n\nuse GD::Graph::Data;\n\n## DESCRIPTION\n\nThis module encapsulates the data structure that is needed for GD::Graph and friends. An object\nof this class contains a list of X values, and a number of lists of corresponding Y values. This\nonly really makes sense if the Y values are numerical, but you can basically store anything.\nUndefined values have a special meaning to GD::Graph, so they are treated with care when stored.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **EXAMPLES**\n- **METHODS**\n- **NOTES**\n- **AUTHOR** (1 subsections)\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "GD::Graph::Data", "section": "", "mode": "perldoc", "summary": "GD::Graph::Data - Data set encapsulation for GD::Graph", "synopsis": "use GD::Graph::Data;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "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]);", "# Add the newer figures from the database", "use DBI;", "# do DBI things, like connecting to the database, statement", "# preparation and execution", "while (@row = $sth->fetchrowarray)", "$data->addpoint(@row);", "my $chart = GD::Graph::bars->new();", "my $gd = $chart->plot($data);", "or for quick changes to legacy code", "# Legacy code builds array like this", "@data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4, 3], [6, 3, 7] );", "# And we quickly need to do some manipulations on that", "my $data = GD::Graph::Data->new();", "$data->copyfrom(\\@data);", "# And now do all the new stuff that's wanted.", "while (@foo = barbaz())", "$data->addpoint(@foo);" ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 8, "subsections": [] }, { "name": "EXAMPLES", "lines": 36, "subsections": [] }, { "name": "METHODS", "lines": 156, "subsections": [] }, { "name": "NOTES", "lines": 4, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [ { "name": "Copyright", "lines": 5 } ] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "GD::Graph::Data - Data set encapsulation for GD::Graph\n", "subsections": [] }, "SYNOPSIS": { "content": "use GD::Graph::Data;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module encapsulates the data structure that is needed for GD::Graph and friends. An object\nof this class contains a list of X values, and a number of lists of corresponding Y values. This\nonly really makes sense if the Y values are numerical, but you can basically store anything.\nUndefined values have a special meaning to GD::Graph, so they are treated with care when stored.\n\nMany of the methods of this module are intended for internal use by GD::Graph and the module\nitself, and will most likely not be useful to you. Many won't even *seem* useful to you...\n", "subsections": [] }, "EXAMPLES": { "content": "use GD::Graph::Data;\nuse GD::Graph::bars;\n\nmy $data = GD::Graph::Data->new();\n\n$data->read(file => '/data/sales.dat', delimiter => ',');\n$data = $data->copy(wanted => [2, 4, 5]);\n\n# Add the newer figures from the database\nuse DBI;\n# do DBI things, like connecting to the database, statement\n# preparation and execution\n\nwhile (@row = $sth->fetchrowarray)\n{\n$data->addpoint(@row);\n}\n\nmy $chart = GD::Graph::bars->new();\nmy $gd = $chart->plot($data);\n\nor for quick changes to legacy code\n\n# Legacy code builds array like this\n@data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4, 3], [6, 3, 7] );\n\n# And we quickly need to do some manipulations on that\nmy $data = GD::Graph::Data->new();\n$data->copyfrom(\\@data);\n\n# And now do all the new stuff that's wanted.\nwhile (@foo = barbaz())\n{\n$data->addpoint(@foo);\n}\n", "subsections": [] }, "METHODS": { "content": "$data = GD::Graph::Data->new()\nCreate a new GD::Graph::Data object.\n\n$data->setx($np, $value);\nSet the X value of point *$np* to *$value*. Points are numbered starting with 0. You probably\nwill never need this. Returns undef on failure.\n\n$data->getx($np)\nGet the X value of point *$np*. See \"setx\".\n\n$data->sety($nd, $np, $value);\nSet the Y value of point *$np* in data set *$nd* to *$value*. Points are numbered starting with\n0, data sets are numbered starting with 1. You probably will never need this. Returns undef on\nfailure.\n\n$data->gety($nd, $np)\nGet the Y value of point *$np* in data set *$nd*. See \"sety\". This will return undef on an\nerror, but the fact that it returns undef does not mean there was an error (since undefined\nvalues can be stored, and therefore returned).\n\n$data->getycumulative($nd, $np)\nGet the cumulative value of point *$np* in data set<$nd>. The cumulative value is obtained by\nadding all the values of the points *$np* in the data sets 1 to *$nd*.\n\n$data->getminmaxx\nReturns a list of the minimum and maximum x value or the empty list on failure.\n\n$data->getminmaxy($nd)\nReturns a list of the minimum and maximum y value in data set $nd or the empty list on failure.\n\n$data->getminmaxyall()\nReturns a list of the minimum and maximum y value in all data sets or the empty list on failure.\n\n$data->addpoint($X, $Y1, $Y2 ...)\nAdds a point to the data set. The base for the addition is the current number of X values. This\nmeans that if you have a data set with the contents\n\n(X1, X2)\n(Y11, Y12)\n(Y21)\n(Y31, Y32, Y33, Y34)\n\na $data->addpoint(Xx, Y1x, Y2x, Y3x, Y4x) will result in\n\n(X1, X2, Xx )\n(Y11, Y12, Y1x)\n(Y21, undef, Y2x)\n(Y31, Y32, Y3x, Y34)\n(undef, undef, Y4x)\n\nIn other words: beware how you use this. As long as you make sure that all data sets are of\nequal length, this method is safe to use.\n\n$data->numsets()\nReturns the number of data sets.\n\n$data->numpoints()\nIn list context, returns a list with its first element the number of X values, and the\nsubsequent elements the number of respective Y values for each data set. In scalar context\nreturns the number of points that have an X value set, i.e. the number of data sets that would\nresult from a call to \"makestrict\".\n\n$data->xvalues()\nReturn a list of all the X values.\n\n$data->yvalues($nd)\nReturn a list of the Y values for data set *$nd*. Data sets are numbered from 1. Returns the\nempty list if $nd is out of range, or if the data set at $nd is empty.\n\n$data->reset() OR GD::Graph::Data->reset()\nAs an object method: Reset the data container, get rid of all data and error messages. As a\nclass method: get rid of accumulated error messages and possible other crud.\n\n$data->makestrict()\nMake all data set lists the same length as the X list by truncating data sets that are too long,\nand filling data sets that are too short with undef values. always returns a true value.\n\n$data->cumulate(preserveundef => boolean)\nThe cumulate parameter will summarise the Y value sets as follows: the first Y value list will\nbe unchanged, the second will contain a sum of the first and second, the third will contain the\nsum of first, second and third, and so on. Returns undef on failure.\n\nif the argument *preserveundef* is set to a true value, then the sum of exclusively undefined\nvalues will be preserved as an undefined value. If it is not present or a false value, undef\nwill be treated as zero. Note that this still will leave undefined values in the first data set\nalone.\n\nNote: Any non-numerical defined Y values will be treated as 0, but you really shouldn't be using\nthis to store that sort of Y data.\n\n$data->wanted(indexes)\nRemoves all data sets except the ones in the argument list. It will also reorder the data sets\nin the order given. Returns undef on failure.\n\nTo remove all data sets except the first, sixth and second, in that order:\n\n$data->wanted(1, 6, 2) or die $data->error;\n\n$data->reverse\nReverse the order of the data sets.\n\n$data->copyfrom($dataref)\nCopy an 'old' style GD::Graph data structure or another GD::Graph::Data object into this object.\nThis will remove the current data. Returns undef on failure.\n\n$data->copy()\nReturns a copy of the object, or undef on failure.\n\n$data->read(*arguments*)\nRead a data set from a file. This will remove the current data. returns undef on failure. This\nmethod uses the standard module Text::ParseWords to parse lines. If you don't have this for some\nodd reason, don't use this method, or your program will die.\n\nData file format: The default data file format is tab separated data (which can be changed with\nthe delimiter argument). Comment lines are any lines that start with a #. In the following\nexample I have replaced literal tabs with for clarity\n\n# This is a comment, and will be ignored\nJan1224\nFeb1337\n# March is missing\nMar\nApr918\n\nValid arguments are:\n\n*file*, mandatory. The file name of the file to read from, or a reference to a file handle or\nglob.\n\n$data->read(file => '/data/foo.dat') or die $data->error;\n$data->read(file => \\*DATA) or die $data->error;\n$data->read(file => $filehandle) or die $data->error;\n\n*nocomment*, optional. Give this a true value if you don't want lines with an initial # to be\nskipped.\n\n$data->read(file => '/data/foo.dat', nocomment => 1);\n\n*delimiter*, optional. A regular expression that will become the delimiter instead of a single\ntab.\n\n$data->read(file => '/data/foo.dat', delimiter => '\\s+');\n$data->read(file => '/data/foo.dat', delimiter => qr/\\s+/);\n\n$data->error() OR GD::Graph::Data->error()\nReturns a list of all the errors that the current object has accumulated. In scalar context,\nreturns the last error. If called as a class method it works at a class level.\n\nThis method is inherited, see GD::Graph::Error for more information.\n\n$data->haserror() OR GD::Graph::Data->haserror()\nReturns true if the object (or class) has errors pending, false if not. In some cases (see\n\"copy\") this is the best way to check for errors.\n\nThis method is inherited, see GD::Graph::Error for more information.\n", "subsections": [] }, "NOTES": { "content": "As with all Modules for Perl: Please stick to using the interface. If you try to fiddle too much\nwith knowledge of the internals of this module, you could get burned. I may change them at any\ntime. Specifically, I probably won't always keep this implemented as an array reference.\n", "subsections": [] }, "AUTHOR": { "content": "Martien Verbruggen \n", "subsections": [ { "name": "Copyright", "content": "(c) Martien Verbruggen.\n\nAll rights reserved. This package is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n" } ] }, "SEE ALSO": { "content": "GD::Graph, GD::Graph::Error\n", "subsections": [] } } } }