One Doc Entry a Day Keeps the Forum Away

[aaronventure]

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

I'm not sure if every single method needs a code snippet (and some are really described fully by the autogenerated one liner), but filling out the gaps of the scripting API docs is on our immediate roadmap anyway (I'm currently going through the scriptnode list), so any help with that is definitely welcomed.

Yeah not every method needs it from the perspective of someone doing this for more than a couple of months, but if you just got here, reading the code example for the clear() method I posted also tells you:

• ah, that's how you do a random integer
• cool, the trace() method is how I convert anything to a string, I guess. Doesn't that have its own entry somewhere?

I'm working off of the KSP documentation example where almost every single method has:

• a short description
• detailed explanation of parameters
• a real-life example
• a link to related or relevant methods

Welcome to KSP

(www.native-instruments.com)

[aaronventure]

Array.concat()

---

Array.concat(var arrayList)

Concatenates (joins) two or more arrays. Ignores non-array argument elements.

var argumentList	A list of arrays. Ignores non-array elements. E.g. arr1, arr2, [4, 5, 6], 7

const var arr1 = [0, 1, [2, 3, 4]];
Console.print(arr1.length); // 3    // the array in the array is counted as a single element

const var arr2 = [5, 6, 7];
const var arr3 = [8, 9, 10];

arr1.concat(arr2);
Console.print(trace(arr1)); // [0, 1, [2, 3, 4], 5, 6, 7]

arr1.concat(arr3);
Console.print(trace(arr1)); // [0, 1, [2, 3, 4], 5, 6, 7, 8, 9, 10]     // the arr1 already contains arr2 

const var arr4 = []; // set type to array
arr4.concat(arr2, arr3, 8726, [11, 12, 13]);
Console.print(trace(arr4)); // [5, 6, 7, 8, 9, 10, 11, 12, 13]   // non-array arguments get ignored // arguments can be arrays themselves

[Christoph Hart]

I've pushed your suggestions and added the find method myself.

The only thing I had to change is the location of the comments:

• descriptive comments that explain stuff go into a single line before the code line
• Console outputs go at the end of the console.print line

This ensures that the most interesting bits are visible without having to scroll in the codebox.

BTW, with the Array API it might make sense to link to the docs of the official Javascript class and highlight differences (if there are any, I tried to stick as close as possible to the official API). For example the find method has this documentation:

Array.prototype.find() - JavaScript | MDN

The find() method of Array instances returns the first element in the provided array that satisfies the provided testing function. If no values satisfy the testing function, undefined is returned.

MDN Web Docs (developer.mozilla.org)

[aaronventure]

@Christoph-Hart Nice.

For concat(), the

// error: arr4 is not of type array

part was in there by mistake. Oops.

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

This ensures that the most interesting bits are visible without having to scroll in the codebox.

Agree

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

BTW, with the Array API it might make sense to link to the docs of the official Javascript class and highlight differences (if there are any, I tried to stick as close as possible to the official API). For example the find method has this documentation:

Array.prototype.find() - JavaScript | MDN

The find() method of Array instances returns the first element in the provided array that satisfies the provided testing function. If no values satisfy the testing function, undefined is returned.

MDN Web Docs (developer.mozilla.org)

Yeah. Same for the String class.

I would highlight in the Basic usage section that each array always has a length property that is written on compilation, and is accessible via array.length. Just to highlight that it's not a class method, but just accessing the property (is that how it's coded in the back? that's how I'm understanding it)

[Christoph Hart]

part was in there by mistake. Oops.

Yeah I was also confused by this, but I was too lazy trying to figure out what you meant with it. I'll remove it with the next batch.

[aaronventure]

Array.isArray()

---

Checks if the given variable is an array.

Array.isArray(var variableToTest)

A simple bool check whether the argument variable is of type array.

Call it on an array, or on the Array class object. If you call it on a non-array variable, the method won't be found and you'll get an error.

const var arr1 = 0;
const var arr2 = [];

var enableSomething = Array.isArray(arr2);
Console.print(enableSomething); // true

var enableSomethingElse = Array.isArray(arr1) && Array.isArray(arr2); 
Console.print(enableSomethingElse); // false

Console.print(arr1.isArray(arr1)); // Error: unknown function `isArray`

[d.healey]

@Christoph-Hart said in One Doc Entry a Day Keeps the Forum Away:

Another thing that could be helpful are simply requests for specific methods that are ridiculously under-documented

array.clone() && object.clone() - these, and a few other commands, don't show up in the API browser at all so you only know about them if you poke around in the source code or watch my videos :)

[aaronventure]

Array.pop()

---

Removes and returns the last element.

Array.pop()

This is useful for managing sequential input that you're keeping track of: history of played notes, velocities, custom undo history etc.

const arr1 = [1, 2, 3];
arr1[4] = 5;

Console.print(arr1.pop()); // 5

// we didn't set the 4th element (index 3) so it'll be undefined
Console.print(arr1.pop()); // error: API call with undefined parameter 

arr1[3] = 22;
Console.print(trace(arr1)); // [1, 2, 3, 22]

// we can check ourselves for errors in our logic in this case
if (isDefined(arr1.pop() 
{
    // do stuff
}

[aaronventure]

@d-healey post an entry

[Christoph Hart]

@aaronventure Lol what's the deal with Array.isArray()? It spits out the wrong value (zero) if I use it with an array and throws an error if it's not an array?

That's gotta be the least useful function in the entire API... I think I'll remove it altogether.

[d.healey]

@Christoph-Hart Works here - I think you guys are using it incorrectly.

[Christoph Hart]

@d-healey Ah, yeah I looked in the source code in order to remove it but that's exactly how it works, but then Aarons example is wrong.

I also noticed that there are a few gems that are not showing up in the API - Array.filter(), Array.some() etc. which are quite powerful functions. I'll investigate.

[aaronventure]

@Christoph-Hart ah fuck. Alright nice, we're already making progress and we're still on the warmup class!

The show starts when we finish with the Array class.

[aaronventure]

Array.reverse()

---

Reverses the order of the elements in the array.

Array.reverse()

_

const var arr1 = [1, 2, 3];
arr1.reverse();
Console.print(trace(arr1)); // [3, 2, 1]

[aaronventure]

Array.remove()

---

Removes all instances of the given element.

Array.remove(var elementToRemove)

const var arr1 = [1, 2, 3, 4, 2, 5,];
arr1.remove(2);

Console.print(trace(arr1)); // [1, 3, 4, 5]

[aaronventure]

Array.removeElement()

---

Removes the element at the given position.

Array.removeElement(int index)

const var arr1 = [1, 2, 3];
Console.print(arr1[1]); // 2

arr1.removeElement(1);
Console.print(arr1[1]); // 3

[aaronventure]

Array,sortNatural()

Sorts array of numbers, objects, or strings with "number in string" priority. Can also sort a combination of all types

Array.sortNatural()

It puts arrays first in index order (doesn't sort them), followed by a mix of int, double and string variables. If a string starts with a number, it'll get thrown in the mix.

JSON objects go last.

const var arr1 = [5.2, 3, "1", "17", [4, 2], [1, 12], "word", "with2", "3LittlePigs", {"prop1": 12, "prop2": 55}];
arr1.sortNatural();
Console.print(trace(arr1)); // [[4, 2], [1, 12], "1", 3, "3LittlePigs", 5.2, "17", {"prop1": 12, "prop2": 55} ]

[aaronventure]

Array.pushIfNotAlreadyThere()

---

Adds the given element at the end and returns the size.

Array.pushIfNotAlreadyThere(var elementToInsert)

The method will not add an element to an array if a matching element already exists inside the array. If an argument is an element that already exists, the return will still be the first index beyond the end of an array (not an index of a first/any matching element).

const arr1 = [0, 1];

arr1.pushIfNotAlreadyThere(2);
Console.print(trace(arr1)); // [0, 1, 2]

// It won't add an element if it already exists in the array
arr1.pushIfNotAlreadyThere(2);
Console.print(trace(arr1)); // [0, 1, 2]

arr1.pushIfNotAlreadyThere(1);
Console.print(trace(arr1)); // [0, 1, 2]

Console.print(arr1.pushIfNotAlreadyThere(1)); // 3

[aaronventure]

Array.map ()

Calls the given function for every array element, and returns an array of individual function returns.

Array.map(var testFunction, var optionalThisObject)

The function takes one argument: the element it's currently processing. This is useful if you want to perform an operation for every single element of an array by passing in a premade function.

An alternative would be to use a for(x in array) loop, but the map method allows for cleaner multidimensional processing.

const arr1 = [0, 1];

arr1.map(function(element)
{
	Console.print(element);
});

Interface: 0
Interface: 1

The method returns an array of individual function returns. If no return exists, the element will be undefined/null.

const arr1 = [0, 1];

const arr2 = arr1.map(function(element)
{
	return element + 10;
});

Console.print(trace(arr2)); // [10, 11]

I think that the optional this is broken, or I'm just not using it correctly (even though this is how it's used for other methods):

const test = 10;
const arr1 = [0, 1];

arr1.map(function(element)
{
	Console.print(this); // error: API call with undefined parameter 0;
}, test);

[aaronventure]

Array.clone()

Return a clone of the array, instantiating a separate data set in the memory.

Array.clone()

If you assign an array object reference to another constant or variable, you're only setting the reference. Making any changes to the array B by referencing it will also make changes to array A. If you need a separate set of data to work on, you need to clone it.

const arr1 = [0, 1];

var arr2 = arr1;

// Changing any element in arr2 will also change it in arr1
arr2[0] = 22;
Console.print(trace(arr1)); // [22, 1]

// Reset the element 0 back to 0
arr1[0] = 0;

// Cloning the array creates a new dataset in memory, separate from the original array
arr2 = arr1.clone();
Console.print(trace(arr1)); [0, 1]
arr2[0] = 22;
Console.print(trace(arr2)); [22, 1]

Because arrays in HISE are effectively objects (which is hinted at by them having a bunch of class methods we're looking at here), this method will also work with any other object, including JSON objects, component references etc.