From 056a863a8daea5e0c3c4a92d9abbe30a7838aad0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Quelin?= Date: Tue, 15 Jan 2008 14:39:16 +0100 Subject: [PATCH] pasted pod from LBV --- lib/Language/Befunge/Vector/XS.pm | 243 ++++++++++++++++++++++++++++---------- 1 file changed, 178 insertions(+), 65 deletions(-) rewrite lib/Language/Befunge/Vector/XS.pm (78%) diff --git a/lib/Language/Befunge/Vector/XS.pm b/lib/Language/Befunge/Vector/XS.pm dissimilarity index 78% index 2cee1e9..4aef918 100644 --- a/lib/Language/Befunge/Vector/XS.pm +++ b/lib/Language/Befunge/Vector/XS.pm @@ -1,65 +1,178 @@ -package Language::Befunge::Vector::XS; - -use 5.008008; -use strict; -use warnings; - -our $VERSION = '0.01'; - -require XSLoader; -XSLoader::load('Language::Befunge::Vector::XS', $VERSION); - -# Preloaded methods go here. - -1; -__END__ -# Below is stub documentation for your module. You'd better edit it! - -=head1 NAME - -Language::Befunge::Vector::XS - Perl extension for blah blah blah - -=head1 SYNOPSIS - - use Math::Vector::XS; - blah blah blah - -=head1 DESCRIPTION - -Stub documentation for Math::Vector::XS, created by h2xs. It looks like the -author of the extension was negligent enough to leave the stub -unedited. - -Blah blah blah. - -=head2 EXPORT - -None by default. - - - -=head1 SEE ALSO - -Mention other useful documentation such as the documentation of -related modules or operating system documentation (such as man pages -in UNIX), or any relevant external documentation such as RFCs or -standards. - -If you have a mailing list set up for your module, mention it here. - -If you have a web site set up for your module, mention it here. - -=head1 AUTHOR - -Jerome Quelin, Er385184@localdomainE - -=head1 COPYRIGHT AND LICENSE - -Copyright (C) 2008 by Jerome Quelin - -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself, either Perl version 5.8.8 or, -at your option, any later version of Perl 5 you may have available. - - -=cut +# +# This file is part of Language::Befunge::Vector::XS. +# Copyright (c) 2008 Jerome Quelin, all rights reserved. +# +# This program is free software; you can redistribute it and/or modify +# it under the same terms as Perl itself. +# +# + +package Language::Befunge::Vector::XS; + +use strict; +use warnings; + +our $VERSION = '0.0.1'; + +require XSLoader; +XSLoader::load('Language::Befunge::Vector::XS', $VERSION); + +# Preloaded methods go here. + +1; +__END__ + +=head1 NAME + +Language::Befunge::Vector::XS - an opaque, N-dimensional vector class. + + + +=head1 SYNOPSIS + + my $v1 = Language::Befunge::Vector::XS->new($x, $y, ...); + my $v2 = Language::Befunge::Vector::XS->new_zeroes($dims); + + + +=head1 DESCRIPTION + +This class abstracts normal vector manipulation. It lets you pass +around one argument to your functions, rather than N arguments, one +per dimension. This means much of your code doesn't have to care +how many dimensions you're working with. + +You can do vector arithmetic, test for equality, or even stringify +the vector to a string like I<"(1,2,3)">. + +It has exactly the same api as C, but LBVXS +is written in XS for speed reasons. + + +=head1 CONSTRUCTORS + +=head2 my $vec = LBV::XS->new( $x [, $y, ...] ) + +Create a new vector. The arguments are the actual vector data; one +integer per dimension. + + +=head2 my $vec = LBV::XS->new_zeroes($dims); + +Create a new vector of dimension C<$dims>, set to the origin (all zeroes). C<< +LBV->new_zeroes(2) >> is exactly equivalent to B<< LBV->new(0,0) >>. + + +=head2 my $vec = $v->copy; + +Return a new LBV object, which has the same dimensions and coordinates +as $v. + + + +=head1 PUBLIC METHODS + +=head2 my $str = $vec->as_string; + +Return the stringified form of C<$vec>. For instance, a Befunge vector +might look like C<(1,2)>. + +This method is also applied to stringification, ie when one forces +string context (C<"$vec">). + + +=head2 my $dims = $vec->get_dims; + +Return the number of dimensions, an integer. + + +=head2 my $val = $vec->get_component($dim); + +Get the value for dimension C<$dim>. + + +=head2 my @vals = $vec->get_all_components; + +Get the values for all dimensions, in order from 0..N. + + +=head2 $vec->clear; + +Set the vector back to the origin, all 0's. + + +=head2 $vec->set_component($dim, $value); + +Set the value for dimension C<$dim> to C<$value>. + + +=head2 my $is_within = $vec->bounds_check($begin, $end); + +Check whether C<$vec> is within the box defined by C<$begin> and C<$end>. +Return 1 if vector is contained within the box, and 0 otherwise. + + + +=head1 MATHEMATICAL OPERATIONS + +=head2 Standard operations + +One can do some maths on the vectors. Addition and substraction work as +expected: + + my $v = $v1 + $v2; + my $v = $v1 - $v2; + +Either operation return a new LBV object, which is the result of C<$v1> +plus / minus C<$v2>. + +The inversion is also supported: + my $v2 = -$v1; + +will subtracts C<$v1> from the origin, and effectively, gives the +inverse of the original vector. The new vector is the same distance from +the origin, in the opposite direction. + + +=head2 Inplace operations + +LBV objects also supports inplace mathematical operations: + + $v1 += $v2; + $v1 -= $v2; + +effectively adds / substracts C<$v2> to / from C<$v1>, and stores the +result back into C<$v1>. + + +=head2 Comparison + +Finally, LBV objects can be tested for equality, ie whether two vectors +both point at the same spot. + + print "same" if $v1 == $v2; + print "differ" if $v1 != $v2; + + +=head1 SEE ALSO + +L + + +=head1 AUTHOR + +Jerome Quelin, Ejquelin@cpan.orgE + +Development is discussed on Elanguage-befunge@mongueurs.netE + + +=head1 COPYRIGHT & LICENSE + +Copyright (c) 2008 Jerome Quelin, all rights reserved. + +This program is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + + +=cut + -- 2.11.4.GIT