package Die;

use strict;
use vars qw($VERSION);

$VERSION = '0.07';

{
   sub _set_face { (shift)->{face} = $_[1] }
}

# Constructor->new sucks.  ->get a Die.
sub get {
   my ( $init, $type, $faced)  = @_;
   my $class = ref($init) || $init;
    
   # To store a face value or not to store . . .
   if ( $faced && $faced == 1 ) {
      return bless { type => $type, face => 0 }, $class;
   } else {
      return bless { type => $type }, $class;
   }
}

sub roll {
   my ( $self, $keeper ) = @_;

   my $type  = $self->{type};
   my $roll  = int( rand($type) + 1 );

   # Optionally stores face value
   if (  defined($self->{face}) && defined($keeper) && $keeper == 1 )
   {
      $self->_set_face($roll);
   }
   return $roll;
}
 
sub face {
   my $self = shift;

   if ( $self->{face} ) {
      return $self->{face}; 
   } else {
      return 0;
   }
}

1;
__END__

=head1 NAME

   Die - Perl module for a base die object  

=head1 SYNOPSIS

   use Die;

   Die->get($type, 1) Where $type is a mandantory parameter 
                      that specifies the number of sides to 
                      the die, and '1' is an optional 
                      parameter used to create a die with a
                      'face' attribute to store the value of
                      the die roll. At creation Die->{face}=0
                      The 0 signifies that the Die has yet to 
                      be rolled.

   Die->roll(1)       Where '1' is an optional parameter
                      that forces the 'face' value to be 
                      stored in a Die object that has been 
                      created with a 'face'. (See Die->get).

=head1 DESCRIPTION 

   This module is a base class for the more robust Dice 
   class.  Although Die methods can be called directly 
   via this module, perfomance begs the question as to 
   why not to just use: 

   int(rnd($num)+1 

   However one may have need of the Dice class and desire 
   to maintain code continuity, and still need a die roll.
   By default Die creates itself as lightweight as possible
   by not creating a 'face' attribute, and by not storing 
   the 'roll'.  Both of these abilities can be enabled by 
   specifiying a an optional parameter of 1.
 
   A comparison of a random number subroutine versus the 
   various incantations of Die->get and Die->roll:

                       Rate    FacedDieObjStored FacedDieObjNotStored 
FacedDieObjStored     8514/s          --                -13%         
FacedDieObjNotStored  9821/s          15%                --           
FacelessDieObj       10110/s          19%                 3%         
RndSubRoutine        54455/s          540%              454%        
   
                               FacelessDieObj     rndSubRoutine
FacedDieObjStored                     -16%              -84%
FacedDieObjNotStored                   -3%              -82%
FacelessDieObj                          --              -81%
RndSubRoutine                         439%                --

=head1 AUTHOR 

coreolyn@bereth.com

=head1 SEE ALSO 

perldoc Dice

=cut

[download]

In reply to Dice::Die by coreolyn

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.