view release on metacpan or  search on metacpan

lib/DataStructure/DoubleList/Node.pm  view on Meta::CPAN

# A node of a double linked list.

package DataStructure::DoubleList::Node;

use strict;
use warnings;
use utf8;
use feature ':5.24';
use feature 'signatures';
no warnings 'experimental::signatures';

use Scalar::Util qw(weaken);

=pod

=head1 NAME

DataStructure::DoubleList::Node

=head1 SYNOPSIS

A single node (element) in a L<DataStructure::DoubleList>.

=head1 DESCRIPTION

=head2 CONSTRUCTOR

You can’t build a node directly. Instead you can call one of the accessors of a
L<DataStructure::DoubleList> or some of the methods below.

Note that a B<DataStructure::DoubleList::Node> does not hold a reference on its
parent list. So a node becomes invalid when the last reference to its list is
deleted as the list itself will be destroyed. But you should also not depend on
this behavior as it might be fixed in the future.

=cut

# The constructor is private and should be called only by this package and its
# parent.
sub new ($class, $list, $prev, $next, $value) {
  my $self = bless {
    list => $list,
    prev => $prev,
    next => $next,
    value => $value,
  }, $class;
  weaken($self->{list});
  return $self;
}

=pod

=head2 METHODS

All the functions below are class methods that should be called on a
C<DataStructure::DoubleList::Node> object.

=over 4

=item value()

Returns the value held by this node.

=cut

sub value ($self) {
  return $self->{value};
}

=pod

=item prev()

Returns the previous B<DataStructure::DoubleList::Node> in this list or B<undef>
if the current object is the first node in its list.

The current node can still be used after that call.

=cut

sub prev ($self) {
  return $self->{prev};
}

=pod

=item next()

Returns the next B<DataStructure::DoubleList::Node> in this list or B<undef>
if the current object is the last node in its list.

The current node can still be used after that call.

=cut

sub next ($self) {
  return $self->{next};
}

=pod

=item insert_after($value)

Inserts a new node in the list after the current one, with the given value and
returns that new node.

The current node can still be used after that call.