The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Math-DifferenceSet-Planar-1.001
River stage zero No dependents
1 ++
/ Math::DifferenceSet::Planar::Data

NAME

Math::DifferenceSet::Planar::Data - storage of sample planar difference sets

VERSION

This documentation refers to version 1.001 of Math::DifferenceSet::Planar::Data.

SYNOPSIS

  use Math::DifferenceSet::Planar::Data;

  $data = Math::DifferenceSet::Planar::Data->new;

  $data = Math::DifferenceSet::Planar::Data->new('pds.db');
  $data = Math::DifferenceSet::Planar::Data->new($full_path);

  @databases = Math::DifferenceSet::Planar::Data->list_databases;
  $data = Math::DifferenceSet::Planar::Data->new($databases[0]);

  $pds = $data->get(9);

  @columns = qw(base exponent modulus n_planes);
  $pds = $data->get(9, @columns);

  $it = $data->iterate($min, $max);
  while (my $pds = $it->()) {
    # ...
  }

  $min   = $data->min_order;
  $max   = $data->max_order;
  $count = $data->count;
  $path  = $data->path;

  $it = $data->iterate_refs('ref_std', $min, $max);
  while (my $pds = $it->()) {
    # ...
  }

  $min   = $data->ref_min_order('ref_std');
  $max   = $data->ref_max_order('ref_lex');
  $count = $data->ref_count('ref_gap');

  $space = $data->get_space(9);
  $min   = $data->sp_min_order;
  $max   = $data->sp_max_order;
  $count = $data->sp_count;

  ($major, $minor) = $data->get_version;
  ($major, $minor) = $data->get_space_version;

DESCRIPTION

Math::DifferenceSet::Planar::Data is a class giving access to a local database of sample planar difference sets, hiding its implementation details. It is used internally by Math::DifferenceSet::Planar to populate difference set objects.

CLASS VARIABLES

$VERSION

$VERSION is the version number of the module.

$DATABASE_DIR

$DATABASE_DIR is the directory containing databases for this module. It is initialized automatically to refer to the location where its data has been installed. It may be set to another absolute path before calling new.

CLASS METHODS

new

Math::DifferenceSet::Planar::Data->new creates a handle for access to a database of difference set samples. Without parameter, it finds a suitable database in the distribution-specific share directory. With a filename parameter, it tries to open that particular database. Relative filenames are resolved relative to the share directory. On success, it returns the handle. On failure, it raises an exception.

list_databases

Math::DifferenceSet::Planar::Data->list_databases returns a list of filenames currently suitable as arguments for new on your platform.

OBJECT METHODS

get

If $data is a Math::DifferenceSet::Planar::Data object, $data->get($order) fetches a single record from the database with order $order. If the database has no record of that order, a false value is returned, otherwise an object of type Math::DifferenceSet::Planar::Schema::Result::DifferenceSet.

$data->get($order, @columns) does the same, but returns a partial record with only the columns that are specified. This is particularly efficient if the delta_main column and thus the main_elements accessor are not needed.

iterate

If $data is a Math::DifferenceSet::Planar::Data object, $data->iterate returns a code reference that, repeatedly called, returns all sample planar difference set records in the database, one by one. The iterator returns a false value when it is exhausted.

$data->iterate($lo, $hi) returns an iterator over all samples with orders between $lo and $hi (inclusively), ordered by ascending size. If $lo is not defined, it is taken as zero. If $hi is omitted or not defined, it is taken as plus infinity. If $lo is greater than $hi, they are swapped and the sequence is reversed, so that it is ordered by descending size.

iterate_properties

If $data is a Math::DifferenceSet::Planar::Data object, $data->iterate_properties(@minmax) behaves exactly like $data->iterate(@minmax), except that the result records have no delta_main component and thus no access to elements. Using this method to browse difference set properties is more efficient than fetching complete records.

With additional arguments after the minimum and maximum order, these arguments are taken as names of components to fetch, so that the resulting records can be even more tailored to what is needed. Minimum and maximum order can not be omitted in that case, but may be undef.

min_order

If $data is a Math::DifferenceSet::Planar::Data object, $data->min_order returns the order of the smallest sample planar difference set in the database.

max_order

If $data is a Math::DifferenceSet::Planar::Data object, $data->max_order returns the order of the largest sample planar difference set in the database.

count

If $data is a Math::DifferenceSet::Planar::Data object, $data->count returns the number of sample planar difference sets in the database.

path

If $data is a Math::DifferenceSet::Planar::Data object, $data->path returns the full path name of the database.

iterate_refs

If $data is a Math::DifferenceSet::Planar::Data object, $data->iterate_refs($type) with $type one of 'ref_std', 'ref_lex', or 'ref_gap', returns a code reference that, repeatedly called, returns all reference planar difference set records of the givent type in the database. The iterator returns a false value when it is exhausted.

Optional arguments after the type argument are minimum and maximum order values in like the optional arguments of iterate.

ref_min_order

This method takes a type argument like iterate_refs and returns the smallest order of available reference sets of that kind, or undef if none are available.

ref_max_order

This method takes a type argument like iterate_refs and returns the largest order of available reference sets of that kind, or undef if none are available.

ref_count

This method takes a type argument like iterate_refs and returns the number of available reference sets of that kind.

get_space

If $data is a Math::DifferenceSet::Planar::Data object, $data->get_space($order) fetches a difference set space record from the database with order $order. If the database has no space record of that order, a false value is returned, otherwise an object of type Math::DifferenceSet::Planar::Schema::Result::DifferenceSetSpace.

Databases may contain more or less spaces than difference sets or even none at all. Spaces speed up enumerating difference set planes but are not depended on in the rest of the library.

iterate_spaces

If $data is a Math::DifferenceSet::Planar::Data object, $data->iterate_spaces returns a code reference that, repeatedly called, returns all planar difference set space records in the database, one by one. The iterator returns a false value when it is exhausted.

$data->iterate($lo, $hi) returns an iterator over all spaces with orders between $lo and $hi (inclusively), ordered by ascending size. If $lo is not defined, it is taken as zero. If $hi is omitted or not defined, it is taken as plus infinity. If $lo is greater than $hi, they are swapped and the sequence is reversed, so that it is ordered by descending size.

sp_min_order

If $data is a Math::DifferenceSet::Planar::Data object, $data->sp_min_order returns the order of the smallest planar difference set space in the database, or undef if no spaces are stored.

sp_max_order

If $data is a Math::DifferenceSet::Planar::Data object, $data->sp_max_order returns the order of the largest planar difference set space in the database, or undef if no spaces are stored.

sp_count

If $data is a Math::DifferenceSet::Planar::Data object, $data->sp_count returns the number of planar difference set spaces in the database. This may be greater or less than the number of sample planar difference sets or even zero.

get_version

If $data is a Math::DifferenceSet::Planar::Data object, $data->get_version returns a pair of numbers matching the planar difference set collection major and minor version reported in the database. Missing version information is treated as major = minor = 0.

get_space_version

If $data is a Math::DifferenceSet::Planar::Data object, $data->get_space_version returns a pair of numbers matching the planar difference set spaces collection major and minor version reported in the database. Missing version information is treated as major = minor = 0.

DIAGNOSTICS

Most methods of this module do not generate diagnostic output nor raise any exceptions.

The new constructor, however, will fail with an exception if the database specified by the optional filename argument or by default is missing or broken.

bad database: <reason>

The database could not be accessed. Diagnostics from underlying libraries such as DBI or File::Share are added, if present.

BUGS AND LIMITATIONS

Bug reports and suggestions are welcome. See the main module on how to contribute.

SEE ALSO

AUTHOR

Martin Becker, <becker-cpan-mp at cozap.com>

COPYRIGHT AND LICENSE

Copyright (c) 2019-2023 by Martin Becker, Blaubeuren.

This library is free software; you can distribute it and/or modify it under the terms of the Artistic License 2.0 (see the LICENSE file).

DISCLAIMER OF WARRANTY

This library is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.