One Doc Entry a Day Keeps the Forum Away

[aaronventure]

Array.clear()

---

Clears the array.

Array.clear()

This is a quick operation (the allocated storage space will not be freed), so you can use it in a realtime callback.

const var arr = []; // Declare an array

for(i = 0; i < 10; i++)
{
	arr[i] = Math.randInt(0, 1000);
}
Console.print(trace(arr)); // [ 523, 5, 76, 345, 765, 45, 977, 223, 44, 54]

arr.clear();

Console.print(trace(arr)); // []

[Christoph Hart]

@aaronventure yup good idea. I'm going to pin this thread.

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.

Another thing that could be helpful are simply requests for specific methods that are ridiculously under-documented - this would be the most low effort contribution one can make to the docs but it gives me the hint on what to prioritize because for me every API method is completely clear and the docs are unnecessary :)

[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