lib/Language/Befunge/Vector/XS.pm

   1 #
   2 # This file is part of Language::Befunge::Vector::XS.
   3 # Copyright (c) 2008 Jerome Quelin, all rights reserved.
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the same terms as Perl itself.
   7 #
   8 #
   9
  10 package Language::Befunge::Vector::XS;
  11
  12 use strict;
  13 use warnings;
  14
  15 use overload
  16         '='   => \&copy,
  17         '+'   => \&_add,
  18         '-'   => \&_substract,
  19         'neg' => \&_invert,
  20         '+='  => \&_add_inplace,
  21     '-='  => \&_substract_inplace,
  22         '<=>' => \&_compare,
  23         '""'  => \&as_string;
  24
  25 our $VERSION = '0.0.1';
  26
  27 require XSLoader;
  28 XSLoader::load('Language::Befunge::Vector::XS', $VERSION);
  29
  30 # Preloaded methods go here.
  31
  32 sub as_string {
  33     my $self = shift;
  34     local $" = ',';
  35     return "(@$self)";
  36 }
  37
  38 sub copy {$_[0]}
  39 sub get_all_components {$_[0]}
  40 sub clear {$_[0]}
  41 sub set_component {$_[0]}
  42 sub bounds_check {$_[0]}
  43 sub _add {$_[0]}
  44 sub _substract {$_[0]}
  45 sub _invert {$_[0]}
  46 sub _add_inplace {$_[0]}
  47
  48 1;
  49 __END__
  50
  51 =head1 NAME
  52
  53 Language::Befunge::Vector::XS - an opaque, N-dimensional vector class.
  54
  55
  56
  57 =head1 SYNOPSIS
  58
  59     my $v1 = Language::Befunge::Vector::XS->new($x, $y, ...);
  60     my $v2 = Language::Befunge::Vector::XS->new_zeroes($dims);
  61
  62
  63
  64 =head1 DESCRIPTION
  65
  66 This class abstracts normal vector manipulation. It lets you pass
  67 around one argument to your functions, rather than N arguments, one
  68 per dimension.  This means much of your code doesn't have to care
  69 how many dimensions you're working with.
  70
  71 You can do vector arithmetic, test for equality, or even stringify
  72 the vector to a string like I<"(1,2,3)">.
  73
  74 It has exactly the same api as C<Language::Befunge::Vector>, but LBVXS
  75 is written in XS for speed reasons.
  76
  77
  78 =head1 CONSTRUCTORS
  79
  80 =head2 my $vec = LBV::XS->new( $x [, $y, ...] )
  81
  82 Create a new vector. The arguments are the actual vector data; one
  83 integer per dimension.
  84
  85
  86 =head2 my $vec = LBV::XS->new_zeroes($dims);
  87
  88 Create a new vector of dimension C<$dims>, set to the origin (all zeroes). C<<
  89 LBV->new_zeroes(2) >> is exactly equivalent to B<< LBV->new(0,0) >>.
  90
  91
  92 =head2 my $vec = $v->copy;
  93
  94 Return a new LBV object, which has the same dimensions and coordinates
  95 as $v.
  96
  97
  98
  99 =head1 PUBLIC METHODS
 100
 101 =head2 my $str = $vec->as_string;
 102
 103 Return the stringified form of C<$vec>. For instance, a Befunge vector
 104 might look like C<(1,2)>.
 105
 106 This method is also applied to stringification, ie when one forces
 107 string context (C<"$vec">).
 108
 109
 110 =head2 my $dims = $vec->get_dims;
 111
 112 Return the number of dimensions, an integer.
 113
 114
 115 =head2 my $val = $vec->get_component($dim);
 116
 117 Get the value for dimension C<$dim>.
 118
 119
 120 =head2 my @vals = $vec->get_all_components;
 121
 122 Get the values for all dimensions, in order from 0..N.
 123
 124
 125 =head2 $vec->clear;
 126
 127 Set the vector back to the origin, all 0's.
 128
 129
 130 =head2 $vec->set_component($dim, $value);
 131
 132 Set the value for dimension C<$dim> to C<$value>.
 133
 134
 135 =head2 my $is_within = $vec->bounds_check($begin, $end);
 136
 137 Check whether C<$vec> is within the box defined by C<$begin> and C<$end>.
 138 Return 1 if vector is contained within the box, and 0 otherwise.
 139
 140
 141
 142 =head1 MATHEMATICAL OPERATIONS
 143
 144 =head2 Standard operations
 145
 146 One can do some maths on the vectors. Addition and substraction work as
 147 expected:
 148
 149     my $v = $v1 + $v2;
 150     my $v = $v1 - $v2;
 151
 152 Either operation return a new LBV object, which is the result of C<$v1>
 153 plus / minus C<$v2>.
 154
 155 The inversion is also supported:
 156     my $v2 = -$v1;
 157
 158 will subtracts C<$v1> from the origin, and effectively, gives the
 159 inverse of the original vector. The new vector is the same distance from
 160 the origin, in the opposite direction.
 161
 162
 163 =head2 Inplace operations
 164
 165 LBV objects also supports inplace mathematical operations:
 166
 167     $v1 += $v2;
 168     $v1 -= $v2;
 169
 170 effectively adds / substracts C<$v2> to / from C<$v1>, and stores the
 171 result back into C<$v1>.
 172
 173
 174 =head2 Comparison
 175
 176 Finally, LBV objects can be tested for equality, ie whether two vectors
 177 both point at the same spot.
 178
 179     print "same"   if $v1 == $v2;
 180     print "differ" if $v1 != $v2;
 181
 182
 183 =head1 SEE ALSO
 184
 185 L<Language::Befunge::Vector>
 186
 187
 188 =head1 AUTHOR
 189
 190 Jerome Quelin, E<lt>jquelin@cpan.orgE<gt>
 191
 192 Development is discussed on E<lt>language-befunge@mongueurs.netE<gt>
 193
 194
 195 =head1 COPYRIGHT & LICENSE
 196
 197 Copyright (c) 2008 Jerome Quelin, all rights reserved.
 198
 199 This program is free software; you can redistribute it and/or modify
 200 it under the same terms as Perl itself.
 201
 202
 203 =cut
 204