Extracting a portion of a string is a fairly well understood practice. With JavaScript, there are three different built-in functions which can perform that operation. Because of this, often it is very confusing for beginners as to which function should be used. Even worse, sometimes it is easy to fall into the trap and choose the wrong function.
String’s substring (ECMAScript 5.1 Specification Section 15.5.4.15) is the first logical choice to retrieve a part of the string. This substring function can accept two numbers, the start and the end (exclusive) character position, respectively. In case the end value is smaller than the start, substring is smart enough to swap the values before doing the string extraction. An example of substring is illustrated in this code snippet:
var a = 'The Three Musketeers';
a.substring(4, 9); 'Three'
a.substring(9, 4); 'Three'
Many JavaScript environments (including most modern web browsers) also implement a variant of substring called substr (Section B.2.3). However, the parameters for substr are the start character position and the numbers of characters to be extracted, respectively. This is shown in the following fragment:
var b = 'The Three Musketeers';
b.substr(4, 9); 'Three Mus'
b.substr(9, 4); ' Mus'
This pair of functions, when they are both available, can be really confusing. It is so easy to mistake one for another and thereby leading to an unexpected outcome. It also does not help that the names, substring and substr, are too similar. Without looking at the documentation or the specification, there is a chance of picking a wrong one.
To add more confusion to this mixture, a String object also supports slice (Section 15.5.4.13), just like in Array’s slice. For all intents and purposes, slice has a behavior very close to substring (accepting start and end position). However, there is a minor difference. If the end value is smaller than the start, slice will not internally swap the values. In other words, it follows what is expected for Array’s slice in the same situation and thus it returns an empty string instead.
var c = 'The Three Musketeers';
c.slice(4, 9); 'Three'
c.slice(9, 4); ''
Each of these three function can accept two parameters and perform the string extraction based on those parameter values. The result however can be different. Again, it is just like in the confusing case of Array methods (see my previous blog post on JavaScript Array: slice vs splice)
When we write our own JavaScript library, how can we minimize such a confusion? The solution is of course to avoid an API which leads to this situation at the first place. Whenever a new public function needs to be introduced, search for existing ones to ensure that there will not be a similar confusion. Of course, it is even better if such a step is enlisted in the API review checklist.
Prevention is the best cure. Be advised of your function name!