OutOfRangeException vs. OutOfBoundsException

Question

PHP defines two SPL exceptions for invalid keys:

OutOfRangeException: Exception thrown when an illegal index was requested. This represents errors that should be detected at compile time.

OutOfBoundsException: Exception thrown if a value is not a valid key. This represents errors that cannot be detected at compile time.

As PHP isn't a compiled language the distinction between compile-time and run-time seems strange and thus I am finding it hard to understand which exception to use when.

Currently my understanding is that one should throw...
... OutOfRangeException if the key is fundamentally and inherently malformed, e.g. if an array is passed as a key.
... OutOfBoundsException if the key is generally okay, but isn't in some boundaries, e.g. if 100 is passed but 50 is the maximum key.

Is that understanding correct?

Answer 1

The confusion in this case comes from a couple of factors. First, PHP is in fact compiled into bytecode. There are several execution environments where this compiled form persists in a relatively permanent form on the server. However, the OutOfRangeException/OutOfBoundsException issue is not about that, it's about a categorization error made by the people who documented these specific exception classes.

Since PHP is dynamically typed, it's often impossible to actually check ranges and even types at compile time. The manual states that OutOfRangeException should be raised at compile time and OutOfBoundsException should apply at runtime, which is an erroneous distinction to make in this context.

Both manual entries use unclear language of what an illegal index means, but looking at the usage of their parent classes gives some clues: LogicExceptions are extended by classes like DomainException, InvalidArgumentException, and LengthException, whereas Runtime exceptions are things such as UnexpectedValueException, OverflowException and UnderflowException. From this pattern one can infer that OutOfRangeException should probably be applied to illegal key types, and OutOfBoundsException should apply to index values that are of the correct type but are not within the bounds of their container.

There was some discussion on the PHP dev list about these categorizations being wrong, but the issue goes deeper than that. In practice, both exceptions can only actually be are raised at runtime. You can use the vagaries of the documentation to squeeze out a distinction between invalid key types and invalid index values, but at this point we're talking about a bug in the PHP documentation.

Answer 2

My own take on this is:

LogicException

use for any mistakes the developer did, e.g. mistakes when programming/assembling the application. Those will hopefully be catched when the developer is running his/her UnitTests (which would then be the equivalent of Compile Time). Those exceptions should never occur on the production site as they are errors in the software as such.

RuntimeException:

use for any mistakes the user did or that result from invalid data put in the application at runtime. These are errors that might be anticipatable but not fully preventable by UnitTests, e.g. those can happen on a production site. Those exceptions could be stemming from incorrect usage or programming errors.

OutOfBounds

is IMO effectively what Wikipedia defines as Range of an Array in Range in Computer Programming, namely:

When an array is numerically indexed, its range is the upper and lower bound of the array. Depending on the environment, a warning, a fatal error, or unpredictable behavior will occur if the program attempts to access an array element that is outside the range.

In other words, when you have an array with indices [0,1,2] anything but [0,1,2] is out of bounds. Note that Bounds can also apply to other data types as well, e.g. trying to access the 7th character in a 5 character string would also be OutOfBounds.

OutOfRange:

this one is a tough cookie. In C++ OutOfRange is a generic exception extending LogicException (just like in PHP). I am not sure if the example given is easily translatable to PHP code though or my definition of Compile time above. Mainly because no one would first init a new Vector(10) and the immediately try to access it at(20).

In Java OutOfRange seems to refer to Range in the mathematical sense

The range of a function is the possible y values of a function that result when we substitute all the possible x-values into the function.

One reference I could find has it extending RuntimeException though, so I guess looking into other languages wont help to solve this mystery. There is also an open bug report about the SPL Exceptions in general, stating that

• OutOfRangeException (value is out of range) is LogicException, should be: RuntimeException

But if this is correct, then how is OutOfRange different from DomainException? And if your own definition is correct, then how is OutOfRange different from InvalidArgumentException?

To cut a long story short: I dont know what OutOfRangeException is supposed to be for.

Answer 3

1. If you get an unexpected index. ie you expect a string but end up with an integer or vice versa. Then you should throw an UnexpectedValueException exception.
2. If you get a proper type of index but it doesn't exist. Then raise a warning (trigger_error) and proceed on. This is not expected to stop programming flow.
3. If you have an object that is iterable or supposed to be iterated over a range and it reaches it's limit (ie the end of a file), then you should throw an OutOfBoundsException.
4. Anything else is a candidate for OutOfRangeException.

In layman's terms. An OutOfBoundsException is something normal. It's not that serious. It's something that happens often and should be taken care of. it can be used by iterators to keep reading data till there is no more to read. It is a logical error. Made by someone using the code not by someone writing the code.

An OutOfRangeException is something serious. Someone should look at the source code. Someone should find out what happened. This is important. Theoretically this was never supposed to happen. Call 911. It is a compile time error. Made by the dummy programmer.

Out of range exceptions are written by programmers to guard against mistakes by other programmers. Or maybe yourself in the future. If you feel like something like that could never happen then use Out Of Range. Use Out of Bounds for something likely to happen.

Answer 4

It is quite simple:

OutOfRange mean "Your requested key is not within the index of a set defined in code."

OutOfBounds means "Your requested key is not within the index of a set defined by loaded configuration."

Answer 5

The answer to your question is quite elusive to me also. However, here are some things to think about:

• If an array is passed in when we are expecting a valid array key, we also have InvalidArgumentException because it is not the proper argument type.
• We could also throw a DomainException because arrays are not in the domain for array keys.
• In php, you generally can't detect types at compile time because of late static binding. They purposefully delay binding of variables to runtime.

How I handle this situation:

• Throw an InvalidArgumentException if a variable is passed in to any function where it the argument is not the correct type. I still do this when working with arrays.
• Throw an InvalidArgumentException if null was passed in when it shouldn't be. This one really could be a lot of things because null isn't typed. To keep error code checking simple, I simply stick with the invalid argument.
• Throw OutOfBoundsException when an index is not in the correct range, just as you suggested.
• Throw BadFunctionCallException if a user-supplied function as a parameter does not have the correct form. If your structure inside is an array, it makes sense that they could pass in a function to modify it, so this comes up occasionally.

Generally, I can use just these three exceptions to represent all errors that occur outside of special resources (Network and database connections would be special resources). The third one seems to have been cropping up more often, but primarily I've just dealt with the former two.

Answer 6

While PHP doesn't have a classic "compile time" (or a compiler that do a lot of static checks for that matter) I'd treat "compile time" as "rather static stuff I did wrong when writing the code" and "run time" as "my logic, input or validation was off at some point".

So my suggestion would be to treat it like this:

"Compile Time" / "OutOfRangeException": The error can always be fixed in the source code without or with very little logic.

I always take numbers from 1-10 and you put in 11

---

"Run Time" / "OutOfBoundsException": The error is due to wrong use at runtime.

You created me and told me to take values from 1 to 5 then you put in 7. Doesn't compute

or

You request an index that is not there because you didn't put it there like you should

---

Sample:

I'd expect an SplFixedArray to throw an OutOfBoundsException because it's size is dynamic and can chance at runtime while I'd expect something like a Calender::getMonthName to throw and OutOfRangeException because the number of month are definitely fixed at "compile/write" time.

Array object sample:

Say $array is an object that implements ArrayAccess you could throw an OutOfBoundsException in these circumstances:

$array['bar'];
$array[7];

As the values are what you could expect for ArrayAccess but it doesn't make sense in the case of an SplFixedArray(5). Alternatives would be DomainException or maybe RangeException

An OutOfRangeException in these cases:

$calendar->getMonth(15);

As putting an array or a new class there is definitely some bigger logic flaw in the code that usually results from a simple "oh, i put in the wrong variable" error by a programmer. An (maybe preferable) alternative would be UnexpectedValueException and good old InvalidArgumentException.

For cases like:

$array[array()];
$array[new StdClass];

some of the alternative exceptions seem more fitting.

Comparisons with the Java world on which exception to use when are not always applicable as Java Developers have an additions issue to deal with.

Checked/Unchecked exceptions. With many people arguing that everything that isn't a runtime exception has very limited use in Java / should not be used much internally) those names have lost some of their original meaning and intent.