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