NAME

Algorithm::Voting::Plurality - use "Plurality" to decide the sole winner

SYNOPSIS

    # construct a "ballot box"
    use Algorithm::Voting::Ballot;
    use Algorithm::Voting::Plurality;
    my $box = Algorithm::Voting::Plurality->new();

    # add ballots to the box
    $box->add( Algorithm::Voting::Ballot->new('Ralph') );
    $box->add( Algorithm::Voting::Ballot->new('Fred') );
    # ... 
    $box->add( Algorithm::Voting::Ballot->new('Ralph') );

    # and print the result
    print $box->as_string;

DESCRIPTION

From http://en.wikipedia.org/wiki/Plurality_voting_system:

The plurality voting system is a single-winner voting system often used to elect executive officers or to elect members of a legislative assembly which is based on single-member constituencies.

The most common system, used in Canada, India, the UK, and the USA, is simple plurality, first past the post or winner-takes-all, a voting system in which a single winner is chosen in a given constituency by having more votes than any other individual representative.

And from http://en.wikipedia.org/wiki/Plurality:

In voting, a plurality vote is the largest number of votes to be given any candidate or proposition when three or more choices are possible. The candidate or proposition receiving the largest number of votes has a plurality. The concept of "plurality" in voting can be contrasted with the concept of "majority". Majority is "more than half". Combining these two concepts in a sentence makes it clearer, "A plurality of votes is a total vote received by a candidate greater than that received by any opponent but less than a majority of the vote."

METHODS

Algorithm::Voting::Plurality->new(%args)

Constructs a "ballot box" object that will use the Plurality criterion to decide the winner. Optionally, specify a list of candidates; any ballot added to the box that does not indicate one of the listed candidates throws an exception.

Example:

    # construct a ballot box that accepts only three candidates
    my @c = qw( John Barack Ralph );
    my $box = Algorithm::Voting::Plurality->new(candidates => \@c);

$box->candidates

Returns a list containing the candidate names used in the construction of the ballot box. If no candidates were specified at construction of the box, the empty list is returned.

$box->add($ballot)

Add $ballot to the box. $ballot can be any object that we can call method candidate() on.

$box->increment_tally($candidate)

Increments the tally for $candidate by 1.

$box->validate_ballot($ballot)

If this election is limited to a specific list of candidates, this method will die() if the candidate on $ballot is not one of them.

count

Returns the total number of ballots cast so far.

result

The result is a "digested" version of the ballot tally, ordered by the number of ballots cast for a candidate.

This method returns a list of arrayrefs, each of the form [$n, @candidates], and sorted by decreasing $n. Candidates "tied" with the same number of votes are lumped together.

For example, an election with three candidates A, B, and C, getting 100, 200, and 100 votes respectively, would generate a result structure like this:

    [
        [ 200, "B" ],
        [ 100, "A", "C" ],
    ]

$box->as_string

Returns a string containing the election results.

cpanm Algorithm::Voting

perl -MCPAN -e shell
install Algorithm::Voting