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