StructFilter

Filters a struct and returns a new struct with the values that pass the filter criteria.

This BIF will invoke the callback function for each entry in the struct, passing the key, value, and the struct itself.

• If the callback returns true, the entry will be included in the new struct.

• If the callback returns false, the entry will be excluded from the new struct.

• If the callback requires strict arguments, it will only receive the key and value.

• If the callback does not require strict arguments, it will receive the key, value, and the original struct.

Parallel Execution

If the parallel argument is set to true, and no max_threads are sent, the filter will be executed in parallel using a ForkJoinPool with parallel streams. If max_threads is specified, it will create a new ForkJoinPool with the specified number of threads to run the filter in parallel, and destroy it after the operation is complete. Please note that this may not be the most efficient way to filter, as it will create a new ForkJoinPool for each invocation of the BIF. You may want to consider using a shared ForkJoinPool for better performance.

Method Signature

StructFilter(struct=[structloose], callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])

Arguments

Argument	Type	Required	Description	Default
struct	struct	true	The target struct to test
callback	function:BiPredicate	true	The function used to filter. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiPredicate which will only receive the first 2 args.
parallel	boolean	false	Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool.	false
maxThreads	any	false	The maximum number of threads to use when running the filter in parallel. If not passed it will use the default number of threads for the ForkJoinPool. If parallel is false, this argument is ignored.
virtual	boolean	false		false

Examples

Example using a simple numeric comparison

Take a struct of items with their rating and use structFilter to return ones of a rating 3 and higher.

Run Example

fruitRatings = { 
	APPLE : 4,
	BANANA : 1,
	ORANGE : 5,
	MANGO : 2,
	KIWI : 3
};
favoriteFruits = structFilter( fruitRatings, ( Any key, Any value ) => {
	return value >= 3;
} );
writedump( favoriteFruits );

Result: {apple=4,orange=5,kiwi=3}

Example using a member function

This is the same example, but using a member function on the struct instead of a standalone function.

Run Example

fruitRatings = { 
	APPLE : 4,
	BANANA : 1,
	ORANGE : 5,
	MANGO : 2,
	KIWI : 3
};
favoriteFruits = fruitRatings.filter( ( Any key, Any value ) => {
	return value >= 3;
} );
writedump( favoriteFruits );

Result: {apple=4,orange=5,kiwi=3}

Additional Examples

Run Example

animals = { 
	COW : "moo",
	PIG : "oink",
	SNAIL : ""
};
// Show all animals
Dump( label="All animals", var=animals );
// Get animals that make noise
noisyAnimals = StructFilter( animals, ( Any key ) => {
	// If the key has a value return true (noisy animal)
	if( Len( animals[ arguments.KEY ] ) ) {
		return true;
	}
	return false;
} );
Dump( label="Noisy Animals", var=noisyAnimals );
// Get animals that are quiet
quietAnimals = StructFilter( animals, ( Any key ) => {
	// If the key has a value return true (quiet animal)
	if( !Len( animals[ arguments.KEY ] ) ) {
		return true;
	}
	return false;
} );
Dump( label="Quiet Animals", var=quietAnimals );

Related

• StructAppend

• StructClear

• StructCopy

• StructDelete

• StructEach

• StructEquals

• StructEvery

• StructFind

• StructFindKey

• StructFindValue

• StructGet

• StructGetMetadata

• StructInsert

• StructIsCaseSensitive

• StructIsOrdered

• StructKeyArray

• StructKeyExists

• StructKeyList

• StructKeyTranslate

• StructMap

• StructNew

• StructNone

• StructReduce

• StructSome

• StructSort

• StructToQueryString

• StructToSorted

• StructUpdate

• StructValueArray