Jérôme Quelin
and 1 contributors

# NAME

Language::Befunge::Vector - an opaque, N-dimensional vector class

version 5.000

# SYNOPSIS

``````    my \$v1 = Language::Befunge::Vector->new(\$x, \$y, ...);
my \$v2 = Language::Befunge::Vector->new_zeroes(\$dims);``````

# 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 "(1,2,3)".

# CONSTRUCTORS

## my \$vec = LB::Vector->new( \$x [, \$y, ...] )

Create a new vector. The arguments are the actual vector data; one integer per dimension.

## my \$vec = LB::Vector->new_zeroes(\$dims);

Create a new vector of dimension `\$dims`, set to the origin (all zeroes). `LBV->new_zeroes(2)` is exactly equivalent to LBV->new(0,0).

## my \$vec = \$v->copy;

Return a new LBV object, which has the same dimensions and coordinates as \$v.

# PUBLIC METHODS

## my \$str = \$vec->as_string;

Return the stringified form of `\$vec`. For instance, a Befunge vector might look like `(1,2)`.

This method is also applied to stringification, ie when one forces string context (`"\$vec"`).

## my \$dims = \$vec->get_dims;

Return the number of dimensions, an integer.

## my \$val = \$vec->get_component(\$dim);

Get the value for dimension `\$dim`.

## my @vals = \$vec->get_all_components;

Get the values for all dimensions, in order from 0..N.

## \$vec->clear;

Set the vector back to the origin, all 0's.

## \$vec->set_component(\$dim, \$value);

Set the value for dimension `\$dim` to `\$value`.

## my \$is_within = \$vec->bounds_check(\$begin, \$end);

Check whether `\$vec` is within the box defined by `\$begin` and `\$end`. Return 1 if vector is contained within the box, and 0 otherwise.

## \$vec->rasterize(\$min, \$max);

Return the next vector in raster order, or undef if the hypercube space has been fully covered.

To enumerate the entire storage area, the caller should call rasterize on the storage area's "min" value the first time, and keep looping while the return value is defined. To enumerate a smaller rectangle, the caller should pass in the min and max vectors describing the rectangle, and keep looping while the return value is defined.

# MATHEMATICAL OPERATIONS

## 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 `\$v1` plus / minus `\$v2`.

The inversion is also supported: my \$v2 = -\$v1;

will subtracts `\$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.

## Inplace operations

LBV objects also supports inplace mathematical operations:

``````    \$v1 += \$v2;
\$v1 -= \$v2;``````

effectively adds / substracts `\$v2` to / from `\$v1`, and stores the result back into `\$v1`.

## 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;``````

# PRIVATE METHODS

## _xs_rasterize_ptr

``    my \$ptr = \$v1->_xs_rasterize_ptr();``

Get a pointer to the C "rasterize" function. Returns undef if LBVXS is not loaded. This is useful for external XS modules, to allow them to call the C function directly for additional speed.

The prototype of the C rasterize function is:

``    AV *rasterize(AV *vec_array, AV *min_array, AV *max_array);``

It operates just like the perl rasterize function, and returns NULL when the end of the loop has been reached.

Jerome Quelin