np

list (lib)

See also: list.type

Description

The list library contains functions and behaviors that operate on lists.

Behaviors

:add( value ) → list

Appends value to the list. This is equivalent to the in-place plus (+=) operator being used on a list.

new l = (: 1 2)
print( l:add(3) )
(: 1 2 3 )

You can also add lists as items to other lists:

new l = (: 1 2)
l:add(: 3 4)
print( l )
(: 1 2 (: 3 4 ) )

:bind( [eventList] ) → list

Returns the event list for this list:

new l1 = (: 1 2 3)
new ListEvents = l1:bind()

If eventList is given, it is bound to the list as its new event list.

new l1 = (: 1 2 3)
-- bind an event list, containing one function named 'first':
l1:bind(: first = { l | => l[1] } )
print(l1:first())
1

:can( functionName ) → boolean

Checks whether the current list responds to events called functionName.

new l1 = (: 10 20 30 )
print( l1:can(#reverse) )
true

:clear( ) → list

Removes all items from the list before returning it.

new l = (: 1 2)
l:clear()
print( l )
(: )

:concat( list2 ) → list

Appends the entries of list2 to the list. This is equivalent to the in-place concatenation operator being used on a list.

new l = (: 1 2)
print( l:concat(:3 4) )
(: 1 2 3 4 )

:containsKeys( list2 ) → boolean

Checks whether the current list contains all the keys of list2.

new l1 = (: ka=10 kb=20 )
new l2 = (: ka=10 kb=20 kc=30 )
new l3 = (: ka=10 )
print( l1:containsKeys(l2) l1:containsKeys(l3) )
false true

:copy( ) → list

Returns a shallow copy of the list.

new l1 = (: 100 200)
new l2 = l1:copy()
l2 += 300
print('l1:' l1)
print('l2:' l2)
l1:	(: 100 200 )
l2:	(: 100 200 300 )

:create( [dataList] ) → list

Creates a new empty list, and binds the current list as its event list. If dataList is given, a copy of it will be used as a data source for the new list.

-- make an event list that inherits from the generic list events
new SayListBehavior = list << (: 
  say = { l | print('I say: ' l:toString()) } 
  ) 
-- make a list bound to this behavior
new myList = SayListBehavior:create(: 1 2 3)
myList:say()
I say: 	(: 1 2 3 )

:each( ƒ⇠item, key ) → list

Calls ƒ on every value in the list.

new l1 = (: 100 200 myKey = 300)
l1:each{ v k | print(k '=' v) }
1	=	100
2	=	200
myKey	=	300

:expand( ) → tuple

Expands a list into a tuple / multiple return value.

new l1 = (: 1 2 3)
new f = { a b c | print('a:' a 'b:' b 'c:' c) }
f( l1:expand() )
a:	1	b:	2	c:	3

:find( searchValue or: ⇠ƒ⇠item,key ) → value

Finds an entry for searchValue in the list and returns its key if it was found, returns nil if no match was found.

new l = (: 10 20 300)
print( l:find(20) )
2

You can use a function ƒ in place of searchValue to provide your own matching code. :find(ƒ) will then return the first non-nil value returned by ƒ:

new l = (: 10 20 300)
print(l:find{ v | if(v == 20) => 'found it, yeah' })
found it, yeah

:get( key )

Retrieves the named entry key from the list, bypassing any :index() event handlers if present.

new l = (: foo = #baz )
print(l:get(#foo))
baz

:iAdd( value ) → list

Returns a new list with the value appended to it. This is equivalent to the plus (+) operator being used on a list.

new l = (: 1 2)
print( l:iAdd(3) )
(: 1 2 3 )

:iConcat( list2 ) → list

Returns a new list that contains the entries of both original lists. This is equivalent to the concatenation operator being used on a list. The mutable version of :iConcat() is called :concat().

new l = (: 1 2)
print( l:iConcat(:3 4) )
(: 1 2 3 4 )

:implements( eventList ) → boolean

Checks whether the current list implements all the events in eventList.

new l1 = (: 10 20 30 )
print( 
  l1:implements(list) 
  l1:implements(: something = 'else' ) 
  )
true false

:insert( position   value ) → list

Mutably inserts the value at position into the list. Position counting starts from 1. A position of 0 means the value gets appended to the end of the list. Negative values count backwards from the end of the list.

new l1 = (: 10 20 30)
l1:insert(-1 25)
print(l1)
(: 10 20 25 30 )

:iReverse( ) → list

Returns a copy of the list with the elements reversed.

new l = (: 10 20 300)
print(l:iReverse())
(: 300 20 10 )

:iSort( sortMode or: ƒ⇠val1, val2 ) → list

Sorts a copy of the list and returns it. list items are compared to each other according to the chosen sortMode, or a custom comparison function ƒ. Valid sort modes are: number (items are interpreted as numerical), string (items are compared as strings), or strict (all items have to be of the same type).

new l = (: 10 2 3 )
print( l:iSort('number') )
print( l:iSort('string') )
(: 2 3 10 )
(: "10" "2" "3" )

:items( ƒ⇠item ) → list

Calls ƒ on every ordered (non-keyed) item in the list.

new l = (: 1 2 myKey=3)
l:items{ v | print(v) }
1
2

:join( seperator ) → string

Returns a string where all ordered items of the list have been joined together, using the seperator in between them.

new l = (: 1 2 myKey=3)
print( l:join(', ') )
1, 2

:keys( ) → list

Returns a list of all the non-numeric keys used in the list.

new l = (: 1 2 myKey=3)
print( l:keys() )
(: 'myKey' )

:map( ƒ⇠item, key ) → list

Calls ƒ on every entry in the list, adding the return values of ƒ into a new list, which is then returned. Whenever ƒ returns nothing, no entry is added to the new list. If two values are returned, the first one is assumed to be the value and the second one the key.

new l = (: 1 2 myKey=3)
print(l:map{ v k | => v+1,k })
(: 2 3 myKey=4 )

:pop( index ) → list

Removes the item at the position index from the list. Positions start with index 1. Values less than zero can be used to address positions counting backward from the end of the list.

new l = (: 1 2 3 )
print(l:pop(-1))
print(l)
3
(: 1 2 )

:reduce( ƒ⇠item, value ) → value

Calls ƒ on every item of the list. The return value of the previous call is passed as the value parameter. The return value of the last call in the chain is also the return value of the :reduce() call.

new l = (: 1 2 3)
-- using reduce to sum all the items in the list
print( l:reduce{ itm val | => itm+val } )
6

:reverse( ) → value

Reverses the order of all non-keyed list items.

new l = (: 1 2 3 )
l:reverse()
print(l)
(: 3 2 1 )

:size( ) → value

Returns the size of the list.

new l = (: 1 2 3 namedEntry = 100 )
print(#items l:size())
print(#named l:keyCount())
items	3
named	1

:set( key   value )

Sets the named entry key to value, bypassing any :newIndex() or :update() event handlers if present.

new l = (: foo = #baz )
l:set(#foo #bar)
print(l)
(: foo="bar" )

:sort( sortMode | ƒ⇠val1, val2 ) → list

Sorts the list, where list items are compared to each other according to the chosen sortMode, or a custom comparison function ƒ. Valid sort modes are: number (items are interpreted as numerical), string (items are compared as strings), or strict (all items have to be of the same type).

new l = (: 10 2 3 )
print( l:sort('number') )
print( l:sort('string') )
(: 2 3 10 )
(: "10" "2" "3" )

:toString( ) → string

Returns a string representation of the list. However, this is not intended as a serialization function.

new l = (: 10 2 3 )
print( l:toString() )
(: 10 2 3)

Library Functions

condense( value1   [value2]   [...] ) → list

Condenses the parameters passed to the function into a list. This works with the variable argument list operator (...) as well.

new f = { ... | print( list.condense(...) ) }
f( 10 20 30 )
(: 10 20 30 n=3 )