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