arrayhack(
ARRAY
,
SEPARATOR
,
SEARCH
,
HACK
)

The arrayhack( function hacks an array by adding, replacing or removing array elements


Parameters

This function has four parameters:

array – the array to be hacked (see Text Arrays).

separator – the separator value for the array. Can be more than one character long.

search – a value to be searched for in the array. The function searches each array element until it finds one that contains this text. The array element doesn’t have to be the same as the text, it only has to contain the text, however, the text must match exactly, including upper and lower case.

hack – the text that will be placed into the array. By default, this text is placed just below the text found by the search parameter (or at the end of the array if there was no match).

If the first character of the hacked text is ∆ (Option-J), the text is inserted above the text found by the search parameter (or at the top of the array if there was no match). (The ∆ character itself is not included in the inserted text.)

If the first character of the hacked text is =, the array element found by the search parameter will be replaced by the hacked text. (The = character is not included.) If there was no match, no change is made to the array.

If the first character of the hacked text is ↩, or the hack text is empty, the array element found by the search parameter will be deleted from the array. If there was no match, no change is made to the array. If the ↩ character is used, you can add a number to delete additional lines above or below the matching line (see below). Note: The ↩ character cannot be generated from the keyboard, so the best way to use it is to copy it from this help file.

Note: If the hack text ends with the separator character, that character is removed before inserting the text into the array. (However, if there is more than one separator at the end, only the last one is removed.)


Description

This function takes an existing array and modifies it by adding, replacing or removing array elements. The function searches for an array element you specify, then performs one of four operations: (1) adds a new array item (or items) below the specified element, (2) adds a new array item (or items) above the specified element, (3) replaces the specified element, or (4) deletes the specified element.

Note: This function only performs one “hack” per search. If multiple array elements match the search text, only the first will be “hacked.”

Inserting Below an Array Element

The default operation is to add a new item (or items) below the specified element. This example inserts white after the green element.

arrayhack("red,green,blue",",","green","white") ☞ red,green,white,blue

You don’t have to specify the entire array element. Since only one element contains the letter “g”, this example works the same as the previous one.

arrayhack("red,green,blue",",","g","white") ☞ red,green,white,blue

If the element you are searching for doesn’t exist, the new element will be added at the end of the array.

arrayhack("red,green,blue",",","orange","white") ☞ red,green,blue,white

Inserting Above an Array Element

To insert above an existing array element, add a ∆ (Option-J) character to the beginning of the new item text. This example inserts white before the green element. (Notice that the ∆ character itself is not inserted.)

arrayhack("red,green,blue",",","green","∆white") ☞ red,white,green,blue

If the element you are searching for doesn’t exist, the new element will be inserted at the beginning of the array.

arrayhack("red,green,blue",",","orange","∆white") ☞ white,red,green,blue

Replacing an Array Element

To replace an existing array element, add an = character to the beginning of the hack text. This example replace green with white.

arrayhack("red,green,blue",",","green","=white") ☞ red,white,blue

Remember that you don’t have to specify the entire array element. This example also replace green with white, even though only the letter “g” was specified.

arrayhack("red,green,blue",",","g","=white") ☞ red,white,blue

If the element you are searching for doesn’t exist, the array is left unchanged.

arrayhack("red,green,blue",",","orange","=white") ☞ red,green,blue

Deleting an Array Element

To delete an existing array element, specify "" (empty text) for the hack parameter. This example removes the green element.

arrayhack("red,green,blue",",","green","") ☞ red,blue

Remember that you don’t have to specify the entire array element. This example also removes the green element, even though only the letter “g” was specified.

arrayhack("red,green,blue",",","g","") ☞ red,blue

If the element you are searching for doesn’t exist, the array is left unchanged.

To delete multiple elements, use ↩ as the hack parameter, followed by a number. If the number is positive, additional elements after the matching element will be removed (whether they match or not). In this example, two elements are removed, green and blue.

arrayhack("red,green,blue,gold,silver,bronze",",","green","↩2") ☞ red,gold,silver,bronze

If the number is negative, additional elements before the matching element will be removed. In this example, three elements will be removed: gold, blue and green.

arrayhack("red,green,blue,gold,silver,bronze",",","gold","↩-3") ☞ red,silver,bronze

Inserting/Replacing Multiple Array Elements

All of the examples so far have shown inserting or replacing with single array elements. To insert/replace multiple array elements, simply include the separator character in the text to be inserted or replaced. This example inserts three colors between green and blue.

arrayhack("red,green,blue",",","green","gold,silver,bronze") ☞ red,green,gold,silver,bronze,blue

Performing Multiple Hack Operations

By adding additional pairs of search/hack parameters, the arrayhack( function can perform multiple “hacks” on the same array. This example adds white after green, then adds gold after red, then changes red to pink.

arrayhack("red,green,blue",",","g","white","r","gold","r","=pink") ☞ pink,gold,green,white,blue

See Also


History

VersionStatusNotes
10.0NewNew in this version.