SYNOPSIS: [total, details] = roll(str)
INPUT str: Dice to be rolled. XdY, where X and Y are scalars, rolls X
fair Y-sided dice. Both X and Y are necessary.
If str is empty or omitted, '1d20' is used as default.
ROLL replaces the dice expression(s) by the rolled result, and
then evaluates the string. This makes it possible to use any
function call as input to ROLL as long as the function name
does not contain the signature of a roll (i.e. a number
followed by the letter 'd' followed by a number). In practice,
if you use ROLL for games, you most likely need only + and -.
There is one special function, XdYbZ, that takes the best Z
rolls out of the X attempts. This is useful to generate
character abilities in role-playing games.
OUTPUT total: total of the roll
details: individual rolls (cell array with results for each
dice in the input
REMARKS (1) If no output is requested, results are printed to screen
(2) Thanks to John D'Errico for pointing out that it is possible
to use any function with roll (as long as it takes the
results of dice rolls as input)
EXAMPLES roll 2d6 rolls two 6-sided dice
roll 1d8+1d4-2 rolls a 8-sided dice, a 4-sided dice and subtracts
2 from the result
roll 1d2 rolls a 2-sided dice (i.e. a coin flip)
roll log(2^1d6) takes the natural logarithm of 2 to the power of
the result of the roll of a 6-sided dice.
roll 1+1 throws an error, because there are no dice to roll.
I still don't see much utility for this, but surely others will find uses.
Note that this is not a vectorized roll code, so if you wanted to use it for a large scale Monte Carlo simulation, you would be disappointed. With the repairs made, and in the context of what this claims to do however, it is well done. So I can see no reason not to rate it as ...
>> roll 1d5
(5) = 5 (*****)
Thank you very much for your detailed investigation! I never thought that roll would work with functions other than '+' or '-', though looking at the code, it turns you that you can use any kind of function as long as it doesn't contain the signature of a roll, and that the output of a dice roll is valid input. I'm glad my function works so well, including giving me a good rating.
I have updated the help according to your suggestions (the file should be up on April 27).
Why anybody would need this, I don't know. I suppose if you were building a game, it might be useful. Regardless, I'll look at it anyway.
The help is reasonable, although not complete. Why do I say not complete? The one thing I found missing is a complete description of how to create the string that it uses. For example, we see that
should roll a single die, with 6 sides. I'd have liked to see a comment that the dice are fair dice, thus each face is equally probable, and that the sides would be numbered 1:6 in this case. I know that, but complete help should be explicit.
The thing I really found missing is a complete description though, rather than just a few examples. For example, this works:
(2+4) = 6
2 dice were rolled, with the total of the two dice returned. Subtract 2 from the sum? No problem.
(1+1)-2 = 0
But what else can I do? There is no mention if we can add two to the sum. I'll try it.
roll('2d4 + 2')
(1+3)+2 = 6
Ok. That worked. How about this one? Does multiply work?
roll('1d4*15 - 23')
(3)*15-23 = 22
Can we divide?
(3)*15/5 = 9
(2)*15/4 = 7.500000e+00
floor((5)/3) = 1
We can find the largest k dice. But is there a way to find the smallest k dice? My question is, what works? Good help will tell us what to expect. We should not need to try all sorts of things to learn how it works.
I should also point out that while many MATLAB functions and operators seem to work here, at least some functionality is definitely not MATLAB syntax, in the case of finding the highest few dice.
The internals of the code are good. regexp is used to parse the string. There are internal comments to explain what happens and why. Variable names were chosen that are descriptive and self-documenting. I found a default string supplied where appropriate, and an error check for at least one logical problem in the input0.
I won't rate this, as I really don't know how to rate something that rolls dice. Perhaps the only logical way is to do this...
(4) = 4
Surprisingly, if I WERE to assign a rating, that is probably close to what I would have chosen here, due to the decent but IMHO, incomplete help.
Improved help based on the suggestions from John D'Errico