In short, the merge() command allows you to merge your current zing with the previous zing in your stack. What’s the stack, you ask?

Recall that, by default, Arrayzing a functional API, meaning that (unless you’re using a mutator command) your zing is never modified. Instead a new one is returned. So, if we do this…

_(1, 4, 9, 144).gteq(4).map(Math.sqrt);

…we have in fact created 3 zings, not one. Although it seems wasteful to keep making new zings, it turns out to be pretty useful. For one, it allows us to step backwards using the undo() command:

_(1, 4, 9, 144)  // [1, 4, 9, 144]
  .gteq(4)        // [4, 9, 144]
  .map(Math.sqrt) // [2, 3, 12]
  .undo()         // [4, 9, 144]
  .undo()         // [1, 4, 9, 144]
  .undo();        // []

(Aside: For those familiar with jQuery, the undo() command is the same as the end() command from that library).

Keeping a history (or stack) also allows us to combine the past with the present using the andSelf() command:

var double = function (x) { return x * 2; };
_(1, 2, 3)    // [1, 2, 3]
  .map(double) // [2, 4, 6]
  .andSelf();  // [2, 4, 6, 1, 2, 3]

But what else? Well, consider this situation: What if we wanted to modify only a subset of a zing? For example, imagine we a list of monetary values and we wanted to make sure they all had the “$” character in front of them. Let’s try and do that without using merge():

var fn = function(e)
{
  if (!e.startsWith("$"))
    return "$" + e;
};
 
_("$1.00", "$1.99", "100.00", "$5").map(fn);

That solution is OK. It’s pretty simple but it still requires a lot of typing and it’s not really using Arrayzing for much (just the map() command). Let’s see if we can reduce the number of keystrokes and make better use of Arrayzing’s capabilities by using the new merge() command:

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/).prepend$("$").merge();

So what just happened there? What does it all mean? Let’s look at that again, and track the contents of the zing:

1
2
3
4
5

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/)    // [ "100.00" ]
  .prepend$("$") // [ "$100.00" ]
  .merge(); 
  // [ "$1.00", "$1.99", "$100.00", "$5" ]

In line 1, we create the Arrayzing (nothing special here). In the following line, we filter out all strings that don’t begin with “$” using a regular expression. Things get a little more interesting on line 3, where we use the mutator version of prepend() to modify the filtered array in-place. Finally, on line 4, we use the merge() command which, basically puts the originally filtered monetary value back into the preceding zing.

So why did we use the prepend$() instead of prepend()? The reason for that is because using prepend() would have created another level of history. For example, here is what would happen if we had used prepend() instead of prepend$():

1
2
3
4

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/)   // [ "100.00" ]
  .prepend("$") // [ "$100.00" ]
  .merge();     // [ "$100.00" ]

Why did that happen? The answer to that question lies in how merge() merges. Let’s start by looking at line 2 of the last code snippet. In that line, we filtered out all strings that did not start with a “$” character. When Arrayzing returns a new zing that contains only the elements that start with a “$”, it also remembers where the new elements came from. So in the case of the not() function on line 2, Arrayzing remembers that “100.00″ came from index 2 of the zing in line 1 (that is, the zing _(“$1.00″, “$1.99″, “100.00″, “$5″)). The merge() command only operates on the current zing and the one immediately previous to it on the stack.

With that in mind, let’s look at line 3. On line 3, we run the prepend() command, which creates and returns a new zing that contains the value “$100.00″. What’s more, it also remembers that the value “$100.00″ was derived from “100.00″ (index 0) in the zing immediately previous to it in the stack (that is, the zing _(“100.00″)). Thus, when merged, it simply overwrites the value it derived from, which is the 0th index of the zing [ "100.00" ]… which results in the zing [ "$100.00" ]. You follow all that?

This concept is easier to understand by annotating the previous code snippet:

var zing1 = _("$1.00", "$1.99", "100.00", "$5");
// [ "$1.00", "$1.99", "100.00", "$5" ] index 0-3 come from nothing
 
var zing2 = zing1.not(/^\$/);
// [ "100.00" ] index 0 comes from index 2 in zing1
 
var zing3 = zing2.prepend("$");
// [ "$100.00" ] index 0 comes from index 0 in zing2
 
var zing4 = zing3.merge();
// [ "$100.00" ] copy index 0 from zing3 over index 0 in zing2

Now, with that more or less explained, let’s go on to one final item: What happens when we try to merge a zing that we’ve added to or removed from. For example, if we added elements like this:

_("str", 2, 3, 4, "a", "b").numbers().add$(7).merge();

What would be in the zing returned by this sequence of functions? In this case, when merge() is called, Arrayzing would not know where to merge the 7 element (since it only remembers the original indices of elements that directly derived from the previous zing). Arrayzing deals with this scenario by simply adding all elements that it does not have an index for to the end of the previous zing in the stack. Here’s what that same snippet would look like if we documented each step:

_("str", 2, 3, 4, "a", "b")
  .numbers() // [ 2, 3, 4 ]
  .add$(7)   // [ 2, 3, 4, 7 ]
  .merge();  // [ "str", 2, 3, 4, "a", "b", 7 ]

How about if we removed elements? If we were to remove elements, they would simply not be merged back into the previous zing on the stack. For example:

_("str", 2, 3, 4, "a", "b")
  .numbers()    // [ 2, 3, 4 ]
  .set$(0, 4)   // [ 4, 3, 4 ]
  .set$(2, 7)   // [ 4, 3, 7 ]
  .removeAt$(0) // [ 3, 7 ]
  .merge();     // [ "str", 2, 3, 7, "a", "b" ]

As you can see, the merge() command is a powerful addition to Arrayzing. It allows us to select a subset of the elements, transform them, and then re-add them to our original zing.

When using plain old JavaScript Array objects, a common operation is to access or modify elements. For example:

var a = [1, 2, 3];
var sum = a[0] + a[1] + a[2]; // = 6
a[0] = 6;
a.join(); // "6,2,3"

Arrayzing also supports the built-in [] accessor. However, it should be noted there are limitations to accessing an Array in this manner, most notable amongst them being that we must always index from the left. For example, imagine we wanted to access the last element. Using a normal Array, we would have to do this:

var a = [1, 2, 3];
a[a.length - 1] = 4; // a = [1, 2, 4];
alert(a[a.length - 1]); // shows 4

Although this works, it’s not the most convenient or elegant way to do it. To address this problem, Arrayzing provides two new functions get() and set(). These functions act essentially the same as the built-in [] accessors with an added benefit: we can index from the left and the right. For example, to implement the above example using Arrayzing, we could instead do this:

var a = _(1, 2, 3);
a.set$(-1, 4); // a = [1, 2, 4];
alert(a.get(-1)); // shows 4

(Aside: If you’re not familiar with the $ after set$(), check out this article. It means that the function is a mutator).

What’s more, all Arrayzing commands that take an index as an argument allow right-indexing. What convenience!

There is one further advantage of using set(): we can change an element in your zing (a zing is an Arrayzing array) without modifying the original array. For example, if we wanted to replace an element in our zing but didn’t want to modify the original array, we would do this:

var a = _(1, 2, 3);
var b = a.set(0, 10); // not set$()
a.str(); // returns "1,2,3"
b.str(); // returns "10,2,3"

As you can see, Arrayzing provides a strict superset of the capabilities of a normal Array’s accessors, allowing you to write cleaner, easier code.

For example, to get all the numbers out of an Arrayzing array (which I have started calling a zing, much to Kevin’s dismay) we would simply have to do this:

_(1, 2, "foo", function() { return 42 }, false, 3, 42).numbers();

Although this is useful in itself, Arrayzing can still do more. Imagine that not only did we want to extract all the numbers in an array, we wanted to sum them too. Arrayzing can handle that without breaking a sweat:

_(1, 2, "foo", function() {}, false, 3, 42).numbers().sum();

And that’s just scratching the surface! But enough about that (we’ll deal with the power of Arrayzing is many posts in the future). Let’s talk about API design.

Arrayzing has been a lot of fun to design. Along the way there have been many design decisions to make and I thought it’d be useful to write about them for the benefit of myself and other would-be API designers.

The first decision I’ll talk about is probably the most radical of the recent changes. It has to do with the functional nature of Arrayzing (which was inherited from jQuery).

Basically, every time an Arrayzing command causes a zing to change (i.e. the numbers() function is invoked), Arrayzing will return a new zing as opposed to just returning a modified version of the current zing. (Remember, a zing is an Arrayzing object). This idea is illustrated below:

// str() is just a convenient way of calling toString()
var a = _(1, "two", 3);
a.str(); // "1,two,3"
var b = a.numbers();
a.str(); // "1,two,3"
b.str(); // "1,3"

This behaviour can be useful in a number of cases. For instance,

var a = _(1, 2, "three", 4, false, function() {}, "foo");
var sum = a.numbers().sum(); // 7
var strings = a.strings().join(","); // "three,foo"

As you can see, we don’t need to keep a copy of the initial values (1, 2, “three”, etc.), we can simply re-use the initial zing. We also won’t accidentally modify a zing when we don’t want to.

However, sometimes we want to modify an array in-place. For example, imagine we had an object called Reader that would read from some data source, and periodically have strings available. In order to check if the Reader has more strings, we would call Reader.hasNext(). In order to read the next string, we would call Reader.next(). So, to read all the strings that Reader has available at a given moment, we would iterate like this:

var array = new Array();
while (Reader.hasNext())
{
  array.push(Reader.next());
}

That same code in Arrayzing, as I’ve described it so far, would be this:

var zing = _();
while (Reader.hasNext())
{
  zing = zing.push(Reader.next());
}

Which has several problems. First of all, it’s not altogether obvious that this is how we’d it. Secondly, it’s pretty inefficent. Every iteration is creating a new Arrayzing that needn’t exist for our purposes. So what’s the solution? Borrow from our friend Ruby and throw in some mutator methods!

In Ruby, when a method modifies an object in-place, it is suffixed with an exclamation mark !. Unfortunately, JavaScript doesn’t allow for us to use exclamation marks in our variables. In place of that, Arrayzing uses the $ character. So now, in Arrayzing, every function that returns a modified zing also has a sister function with a suffixed $ that will modify the zing in-place.

Thus, returning to the example with the Reader, we can now use a mutator function:

var zing = _();
while (Reader.hasNext())
{
  zing.push$(Reader.next());
}