GD::Graph::Data - phpMan

NAME
    GD::Graph::Data - Data set encapsulation for GD::Graph

SYNOPSIS
    use GD::Graph::Data;

DESCRIPTION
    This module encapsulates the data structure that is needed for GD::Graph
    and friends. An object of this class contains a list of X values, and a
    number of lists of corresponding Y values. This only really makes sense
    if the Y values are numerical, but you can basically store anything.
    Undefined values have a special meaning to GD::Graph, so they are
    treated with care when stored.

    Many of the methods of this module are intended for internal use by
    GD::Graph and the module itself, and will most likely not be useful to
    you. Many won't even *seem* useful to you...

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->fetchrow_array)
      {
          $data->add_point(@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->copy_from(\@data);

      # And now do all the new stuff that's wanted.
      while (@foo = bar_baz())
      {
          $data->add_point(@foo);
      }

METHODS
  $data = GD::Graph::Data->new()
    Create a new GD::Graph::Data object.

  $data->set_x($np, $value);
    Set the X value of point *$np* to *$value*. Points are numbered starting
    with 0. You probably will never need this. Returns undef on failure.

  $data->get_x($np)
    Get the X value of point *$np*. See "set_x".

  $data->set_y($nd, $np, $value);
    Set the Y value of point *$np* in data set *$nd* to *$value*. Points are
    numbered starting with 0, data sets are numbered starting with 1. You
    probably will never need this. Returns undef on failure.

  $data->get_y($nd, $np)
    Get the Y value of point *$np* in data set *$nd*. See "set_y". This will
    return undef on an error, but the fact that it returns undef does not
    mean there was an error (since undefined values can be stored, and
    therefore returned).

  $data->get_y_cumulative($nd, $np)
    Get the cumulative value of point *$np* in data set<$nd>. The cumulative
    value is obtained by adding all the values of the points *$np* in the
    data sets 1 to *$nd*.

  $data->get_min_max_x
    Returns a list of the minimum and maximum x value or the empty list on
    failure.

  $data->get_min_max_y($nd)
    Returns a list of the minimum and maximum y value in data set $nd or the
    empty list on failure.

  $data->get_min_max_y_all()
    Returns a list of the minimum and maximum y value in all data sets or
    the empty list on failure.

  $data->add_point($X, $Y1, $Y2 ...)
    Adds a point to the data set. The base for the addition is the current
    number of X values. This means that if you have a data set with the
    contents

      (X1,  X2)
      (Y11, Y12)
      (Y21)
      (Y31, Y32, Y33, Y34)

    a $data->add_point(Xx, Y1x, Y2x, Y3x, Y4x) will result in

      (X1,    X2,    Xx )
      (Y11,   Y12,   Y1x)
      (Y21,   undef, Y2x)
      (Y31,   Y32,   Y3x,  Y34)
      (undef, undef, Y4x)

    In other words: beware how you use this. As long as you make sure that
    all data sets are of equal length, this method is safe to use.

  $data->num_sets()
    Returns the number of data sets.

  $data->num_points()
    In list context, returns a list with its first element the number of X
    values, and the subsequent elements the number of respective Y values
    for each data set. In scalar context returns the number of points that
    have an X value set, i.e. the number of data sets that would result from
    a call to "make_strict".

  $data->x_values()
    Return a list of all the X values.

  $data->y_values($nd)
    Return a list of the Y values for data set *$nd*. Data sets are numbered
    from 1. Returns the empty list if $nd is out of range, or if the data
    set at $nd is empty.

  $data->reset() OR GD::Graph::Data->reset()
    As an object method: Reset the data container, get rid of all data and
    error messages. As a class method: get rid of accumulated error messages
    and possible other crud.

  $data->make_strict()
    Make all data set lists the same length as the X list by truncating data
    sets that are too long, and filling data sets that are too short with
    undef values. always returns a true value.

  $data->cumulate(preserve_undef => boolean)
    The cumulate parameter will summarise the Y value sets as follows: the
    first Y value list will be unchanged, the second will contain a sum of
    the first and second, the third will contain the sum of first, second
    and third, and so on. Returns undef on failure.

    if the argument *preserve_undef* is set to a true value, then the sum of
    exclusively undefined values will be preserved as an undefined value. If
    it is not present or a false value, undef will be treated as zero. Note
    that this still will leave undefined values in the first data set alone.

    Note: Any non-numerical defined Y values will be treated as 0, but you
    really shouldn't be using this to store that sort of Y data.

  $data->wanted(indexes)
    Removes all data sets except the ones in the argument list. It will also
    reorder the data sets in the order given. Returns undef on failure.

    To remove all data sets except the first, sixth and second, in that
    order:

      $data->wanted(1, 6, 2) or die $data->error;

  $data->reverse
    Reverse the order of the data sets.

  $data->copy_from($data_ref)
    Copy an 'old' style GD::Graph data structure or another GD::Graph::Data
    object into this object. This will remove the current data. Returns
    undef on failure.

  $data->copy()
    Returns a copy of the object, or undef on failure.

  $data->read(*arguments*)
    Read a data set from a file. This will remove the current data. returns
    undef on failure. This method uses the standard module Text::ParseWords
    to parse lines. If you don't have this for some odd reason, don't use
    this method, or your program will die.

    Data file format: The default data file format is tab separated data
    (which can be changed with the delimiter argument). Comment lines are
    any lines that start with a #. In the following example I have replaced
    literal tabs with <tab> for clarity

      # This is a comment, and will be ignored
      Jan<tab>12<tab>24
      Feb<tab>13<tab>37
      # March is missing
      Mar<tab><tab>
      Apr<tab>9<tab>18

    Valid arguments are:

    *file*, mandatory. The file name of the file to read from, or a
    reference to a file handle or glob.

      $data->read(file => '/data/foo.dat') or die $data->error;
      $data->read(file => \*DATA) or die $data->error;
      $data->read(file => $file_handle) or die $data->error;

    *no_comment*, optional. Give this a true value if you don't want lines
    with an initial # to be skipped.

      $data->read(file => '/data/foo.dat', no_comment => 1);

    *delimiter*, optional. A regular expression that will become the
    delimiter instead of a single tab.

      $data->read(file => '/data/foo.dat', delimiter => '\s+');
      $data->read(file => '/data/foo.dat', delimiter => qr/\s+/);

  $data->error() OR GD::Graph::Data->error()
    Returns a list of all the errors that the current object has
    accumulated. In scalar context, returns the last error. If called as a
    class method it works at a class level.

    This method is inherited, see GD::Graph::Error for more information.

  $data->has_error() OR GD::Graph::Data->has_error()
    Returns true if the object (or class) has errors pending, false if not.
    In some cases (see "copy") this is the best way to check for errors.

    This method is inherited, see GD::Graph::Error for more information.

NOTES
    As with all Modules for Perl: Please stick to using the interface. If
    you try to fiddle too much with knowledge of the internals of this
    module, you could get burned. I may change them at any time.
    Specifically, I probably won't always keep this implemented as an array
    reference.

AUTHOR
    Martien Verbruggen <mgjv AT tradingpost.au>

  Copyright
    (c) 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.

SEE ALSO
    GD::Graph, GD::Graph::Error