Last updated
Was this helpful?
Last updated
Was this helpful?
Almost every programming language allows you to represent different types of collections. In BoxLang, we have three types of collections: arrays, , and .
An array is a number-indexed list. Imagine you had a blank piece of paper and drew a set of three small boxes in a line:
You could number each one by its position from left to right:
Then put strings in each box:
We have a three-element Array. BoxLang arrays can grow and shrink dynamically at runtime, just like Array Lists or Vectors in Java, so if we added an element, it’d usually go on the end or be appended at the end.
If you asked the array for the element in position two, you’d get back Lunch
. Ask for the last element, and you’ll get back: Dessert
.
Now, have you detected something funny with the ordering of the elements? Come on, look closer....... They start with 1
and not 0
, now isn't that funny. BoxLang is one of the few languages where array indexes start at 1
and not 0
. So if you have a PHP, Ruby, or Java background, remember that 1
is where you start. Is this good or bad? Well, we will refrain from pointing fingers for now.
Let's do some code samples:
Tip: You can use the toString()
call on any array to get a string representation of its values: grid.toString()
While BoxLang arrays are inherently one-dimensional, you can create multi-dimensional structures by nesting arrays within arrays. This approach provides flexibility for representing matrices, tables, grids, and other complex data structures.
Consistent Structure: Ensure all sub-arrays have the same length when representing regular grids
Bounds Checking: Always verify array indices exist before accessing nested elements
Memory Considerations: Large multi-dimensional arrays can consume significant memory
Initialization: Pre-populate arrays with default values to avoid null reference errors
Documentation: Clearly document the expected structure and dimensions of your nested arrays
Multi-dimensional arrays in BoxLang provide powerful data organization capabilities while maintaining the simplicity of single-dimensional array operations.
BoxLang also supports the concept of negative indices. This allows you to retrieve the elements from the end of the array backward. So you can easily count back instead of counting forwards:
Tip: You can also use negative offsets.
You can use different constructs for looping over arrays:
for
loops
loop
constructs
each()
closures
BoxLang allows you to leverage the each()
operations in a multi-threaded fashion. The arrayEach()
or each()
functions allow for a parallel
and maxThreads
arguments so the iteration can happen concurrently on as many maxThreads
as supported by your JVM.
This is incredibly awesome, as your callback will now be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that scoping is done correctly and that appropriate locking strategies are in place when accessing shared scopes and/or resources. Here is where unmodifiable arrays, structs, and queries can help.
Coming soon, still in development
Arrays also allow the usage of the spread operator syntax to quickly copy all or part of an existing array or object into another array or object. This operator is used by leveraging three dots ...
in specific expressions.
The Spread syntax allows an iterable such as an array expression or string, to be expanded in places where zero or more arguments (for function calls) or elements (for array literals) are expected. Here are some examples to help you understand this operator:
Coming soon, still in development
The rest operator is similar to the spread operator but behaves oppositely. Instead of expanding the literals, it contracts them into an array you designate via the ...{name}
syntax. You can use this to define endless arguments for a function, for example. In this case, I can create a dynamic findBy
function that takes in multiple criteria name-value pairs.
BoxLang supports trailing commas when defining array and struct literals. Just in case you miss a dangling comma, we won't shout at you!
All arrays and structures offer the ability to listen to changes to themselves. This is all done via our $bx
metadata object available on all arrays/structures. You will call the registerChangeListener()
function to register a closure/lambda that will listen to changes on the array. You can listen:
To all changes in the array
To a specific index in the array
However, you must EXPLICITLY return the value that will be stored in the change.
Please note that this change listener will fire on every array access, so ensure it's performant.
The signature of the closure/lambda is the following
Please note that the Key is a BoxLang Key object, which simulates a case-insensitive string. You can use methods on it like:
getName()
getNameNoCase()
toString()
Here are a few simple examples:
Here is another example when listening to a specific index:
Please note that all member functions can also be used as traditional . However, look much better for readability.
The best way to learn about using arrays is to check out the available and .
BoxLang supports the of an array via the arraySlice()
method or the slice()
member function, respectively. Slicing allows you to return a new array from the start position up to the count of elements you want.
An array is a data structure consisting of a collection of elements.