=encoding UTF-8

=head1 NAME

TCOD::Dijkstra - An Dijkstra pathfinder

=head1 SYNOPSIS

    use TCOD;

    my $map = TCOD::Map->new( 10, 10 );
    $map->clear( 1, 1 );

    my $path = TCOD::Dijkstra->new( $map, 1.41 );

    $path->compute(  3, 0 );
    $path->path_set( 9, 9 );

    printf "Step to [%s,%s]\n", $path->get($_) for 0 .. $path->size - 1;
    # OUTPUT:
    # Step to [3,1]
    # Step to [3,2]
    # Step to [3,3]
    # Step to [4,4]
    # Step to [5,5]
    # Step to [6,6]
    # Step to [7,7]
    # Step to [8,8]
    # Step to [9,9]

=head1 DESCRIPTION

This class implements a Dijkstra pathfinder.

=head1 METHODS

=head2 new

    $path = TCOD::Dijkstra->new( $map, $diagonal_cost );

Takes a L<TCOD::Map> object and a diagonal cost value and returns a
TCOD::Dijkstra object that can be used to find paths in that map.

The diagonal cost will determine the cost of diagonal movement compared
to orthogonal movement. A good standard value to use is 1.41 (C<~sqrt(2)>).
Set to 0 to disable diagonal movement entirely, or 1 to make all directions
have the same cost.

=head2 compute

    $path->compute( $origin_x, $origin_y );

Takes the coordinates of a starting position and computes an Dijkstra map
with the distance from that point to every other cell in the map.

=head2 path_set

    $bool = $path->path_set( $destination_x, $destination_y );

=head2 reverse

    $path->reverse;

Reverses the origin and destination points for this path.

=head2 size

    $steps = $path->size;

Returns the number of steps in this path. This number will remain constant
as long as the object's start and destination points haven't changed after
computing a path.

=head2 get_distance

    $distance = $path->get_distance( $x, $y );

Returns the distance between the origin coordinates, and the specified
coordinates. If the specified coordinates are not walkable, or are outside
of the map, this method returns -1.

=head2 get

    ( $x, $y ) = $path->get( $step );

Returns a list with the coordinates of the specified step. Together with
L<size|/size>, this can be used to iterate through a path.

=head1 SEE ALSO

=over

=item L<TCOD>

=item L<TCOD::Map>

=item L<TCOD::Path>

=back

=head1 COPYRIGHT AND LICENSE

Copyright 2021 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.
