# Oops...

This website is made for modern browsers. You are seeing this, because your browser is missing a feature or two. Please install the latest update or switch to a modern browser. See you soon.

# Filter lists

#lists

The methods presented below can be used to extract or remove items or subsets from lists. The components operate on given indices or patterns of Boolean values. The how-to Search lists deals with a similar operation: searching lists for specific items.

### Retrieve items per index (List Item)

The component List Item

List Item (Item)
Sets  >  List  >  List Item
Retrieve a specific item from a list.
Inputs
List (L)Base list
Index (i)Item index
Wrap (W)Wrap index to list bounds
Outputs
Item (i)Item at {i'}
can be used to fetch specific items from a list L by a given index i. If input W (Wrap) is set to True, the index enumeration of the list will repeat from the beginning, in case that the index exceeds the number of items in the list.

Sometimes, we only need the first and last index of a list. We can zoom in on a List Item

List Item (Item)
Sets  >  List  >  List Item
Retrieve a specific item from a list.
Inputs
List (L)Base list
Index (i)Item index
Wrap (W)Wrap index to list bounds
Outputs
Item (i)Item at {i'}
component and add an extra output at the top via the ZUI. By default, input i is set to 0, the new output is then -1 and thus gives us the last item of the list.

### Separate lists (Split List)

The component Split List

Split List (Split)
Sets  >  List  >  Split List
Split a list into separate parts.
Inputs
List (L)Base list
Index (i)Splitting index
Outputs
List A (A)Items to the left of (i)
List B (B)Items to the right of and including (i)
will separate a list L in two parts. Index i states the item that will be the first one on the second list.

### Subdivide lists (Partition List)

The component Partition List

Partition List (Partition)
Sets  >  List  >  Partition List
Partition a list into sub-lists
Inputs
List (L)List to partition
Size (S)Size of partitions
Outputs
Chunks (C)List chunks
will subdivide a list L into subsets. Their length is given by input S.

### Extract a subset (Sub List)

The component Sub List

Sub List (SubSet)
Sets  >  List  >  Sub List
Extract a subset from a list.
Inputs
List (L)Base list
Domain (D)Domain of indices to copy
Wrap (W)Remap indices that overshoot list domain
Outputs
List (L)Subset of base list
Index (I)Indices of subset items
will extract a subset from a List L, according to the domain provided at input D.

### Remove items per index (Cull Index)

The component Cull Index

Cull Index (Cull i)
Sets  >  Sequence  >  Cull Index
Cull (remove) indexed elements from a list.
Inputs
List (L)List to cull
Indices (I)Culling indices
Wrap (W)Wrap indices to list range
Outputs
List (L)Culled list
will remove items from a List L, according to the indices given at input I. This component resembles the opposite of List Item
List Item (Item)
Sets  >  List  >  List Item
Retrieve a specific item from a list.
Inputs
List (L)Base list
Index (i)Item index
Wrap (W)Wrap index to list bounds
Outputs
Item (i)Item at {i'}
.

### Remove every nth item (Cull Nth)

The component Cull Nth

Cull Nth (CullN)
Sets  >  Sequence  >  Cull Nth
Cull (remove) every Nth element in a list.
Inputs
List (L)List to cull
Cull frequency (N)Cull frequency
Outputs
List (L)Culled list
will remove every nth item from a list L. The frequency is given by input N.

### Remove random items (Random Reduce)

The component Random Reduce

Random Reduce (Reduce)
Sets  >  Sequence  >  Random Reduce
Randomly remove N items from a list
Inputs
List (L)List to reduce
Reduction (R)Number of items to remove
Seed (S)Random Generator Seed value
Outputs
List (L)Reduced list
will randomly remove a given number of items R from a list L. Simultaneously, the original order of the items is scrambled. We can influence the randomness by providing an alternative Seed S.

### Remove items by using a mask (Cull Pattern)

The component Cull Pattern

Cull Pattern (Cull)
Sets  >  Sequence  >  Cull Pattern
Cull (remove) elements in a list using a repeating bit mask.
Inputs
List (L)List to cull
Cull Pattern (P)Culling pattern
Outputs
List (L)Culled list
will remove items from a list L, according to a pattern P of Boolean values. If the number of items in the list exceeds the length of the pattern, the pattern is repeated until all items are processed. By right-clicking input P and selecting Invert, the pattern can be inverted (False will become True etc.).

### Get the complement of a set

To get the complement of a set, we need the set itself and the universal set ($A^C = U\backslash A$). If the sets consist of or can be converted into Primitive Data Types, we can use the component Set Difference

Set Difference (Difference)
Sets  >  Sets  >  Set Difference
Create the difference of two sets (the collection of objects present in A but not in B).
Inputs
Set A (A)Set to subtract from.
Set B (B)Substraction set.
Outputs
Union (U)The Set Difference of A minus B
to get the complement. Otherwise, we can get the indices of our subset with Item Index
Item Index (Index)
Sets  >  List  >  Item Index
Retrieve the index of a certain item in a list.
Inputs
List (L)List to search
Item (i)Item to search for
Outputs
Index (i)The index of item in the list, or -1 if the item could not be found.
and use Cull Index
Cull Index (Cull i)
Sets  >  Sequence  >  Cull Index
Cull (remove) indexed elements from a list.
Inputs
List (L)List to cull
Indices (I)Culling indices
Wrap (W)Wrap indices to list range
Outputs
List (L)Culled list
to remove the subset from our universal set to get the complement.

If we have the indices, but they occur multiple times, we can use Create Set

Create Set (CSet)
Sets  >  Sets  >  Create Set
Creates the valid set from a list of items (a valid set only contains distinct elements).
Inputs
List (L)List of data.
Outputs
Set (S)A set of all the distincts values in L
Map (M)An index map from original indices to set indices
on the whole list of indices to get unique values at output S. We then use List Item
List Item (Item)
Sets  >  List  >  List Item
Retrieve a specific item from a list.
Inputs
List (L)Base list
Index (i)Item index
Wrap (W)Wrap index to list bounds
Outputs
Item (i)Item at {i'}
and Cull Index
Cull Index (Cull i)
Sets  >  Sequence  >  Cull Index
Cull (remove) indexed elements from a list.
Inputs
List (L)List to cull
Indices (I)Culling indices
Wrap (W)Wrap indices to list range
Outputs
List (L)Culled list
to generate the two complementary lists.

### Dispatch items into two target lists (Dispatch)

The component Dispatch

Dispatch (Dispatch)
Sets  >  List  >  Dispatch
Dispatch the items in a list into two target lists.
Inputs
List (L)List to filter
Dispatch pattern (P)Dispatch pattern
Outputs
List A (A)Dispatch target for True values
List B (B)Dispatch target for False values
will send the items of list L to one of the two target lists, according to the pattern of Boolean values provided at input P. If the number of items exceeds the number of Boolean values, the pattern is repeated. We get all items, whose corresponding Boolean was True, at output A and vice versa at for output B.

Before we can use Dispatch

Dispatch (Dispatch)
Sets  >  List  >  Dispatch
Dispatch the items in a list into two target lists.
Inputs
List (L)List to filter
Dispatch pattern (P)Dispatch pattern
Outputs
List A (A)Dispatch target for True values
List B (B)Dispatch target for False values
, we have to create the list of Boolean values, which is often the more effortful task. The components found in the ribbon tab Math in group Operators can be used for simple logical comparisons. The components Evaluate
Evaluate (Eval)
Maths  >  Script  >  Evaluate
Evaluate an expression with a flexible number of variables.
Inputs
Expression (F)Expression to evaluate
Variable x (x)Expression variable
Variable y (y)Expression variable
Outputs
Result (r)Expression result
and Expression
Expression (Expression)
Maths  >  Script  >  Expression
Evaluate an expression
Inputs
Variable x (x)Expression variable
Variable y (y)Expression variable
Outputs
Result (R)Result of expression
can be used for more advanced operators. Also, components with analysis functionality, like Point In Brep
Point In Brep (BrepInc)
Surface  >  Analysis  >  Point In Brep
Test whether a point is inside a closed brep
Inputs
Brep (B)Brep for inclusion test
Point (P)Point for inclusion test
Strict (S)If true, then the inclusion is strict
Outputs
Inside (I)True if point is on the inside of the Brep.
or Is Planar
Is Planar (Planar)
Surface  >  Analysis  >  Is Planar
Test whether a surface is planar
Inputs
Surface (S)Surface to test for planarity
Interior (I)Limit planarity test to the interior of trimmed surfaces
Outputs
Planar (F)Planarity flag of surface
Plane (P)Surface plane
, will output a list of Boolean values. You will also find more examples of generating Booleans in the how-to conditional-statements
.

### Dispatch items into multiple target lists (e.g. filter by type)

As written above, Dispatch

Dispatch (Dispatch)
Sets  >  List  >  Dispatch
Dispatch the items in a list into two target lists.
Inputs
List (L)List to filter
Dispatch pattern (P)Dispatch pattern
Outputs
List A (A)Dispatch target for True values
List B (B)Dispatch target for False values
has only two target lists (one for True and one for False). However, by combining some components, we can write a filter that handles any type of filtering. This is done by checking each criterion and then dispatching the matches to separate branches of a data tree.

The following example shows how to filter a list of geometric objects into separate lists for each type. The idea is to test each item with string comparison, whether it matches one of our criteria. But before we can do this, we have to cast all objects into string format, which is done by a Text

Text (Txt)
Params  >  Primitive  >  Text
Contains a collection of text fragments
container. We can then use Expression
Expression (Expression)
Maths  >  Script  >  Expression
Evaluate an expression
Inputs
Variable x (x)Expression variable
Variable y (y)Expression variable
Outputs
Result (R)Result of expression
and the notation Contains(x,y) to test, if a string contains any of the strings that we provide in a Panel
Panel
Params  >  Input  >  Panel
A panel for custom notes and text values
at the other input.
Points are not cast by their type name but by their coordinates. Here we test, if the character { is present, to identify a point.
Points are not cast by their type name but by their coordinates. Here we test, if the character { is present, to identify a point. To ensure that every object is matched with every string, we have to graft input y.

After the custom evaluation, we can filter the list with a Dispatch

Dispatch (Dispatch)
Sets  >  List  >  Dispatch
Dispatch the items in a list into two target lists.
Inputs
List (L)List to filter
Dispatch pattern (P)Dispatch pattern
Outputs
List A (A)Dispatch target for True values
List B (B)Dispatch target for False values
component. The positive matches for each type are in separate branches and we can attach an Explode Tree
Explode Tree (BANG!)
Sets  >  Tree  >  Explode Tree
Extract all the branches from a tree
Inputs
Data (D)Data to explode
Outputs
Branch 0 (-)All data inside the branch at index: 0
Branch 1 (-)All data inside the branch at index: 1
component at output A to find our separated lists.

The task of filtering a list by type can also be achieved with a C# Script

C# Script (C#)
Maths  >  Script  >  C# Script
A C#.NET scriptable component
Inputs
x (x)Script Variable x
y (y)Script Variable y
Outputs
out (out)Print, Reflect and Error streams
A (A)Output parameter A
component. How to code this is explained here
.

### Separate items into multiple lists by an integer pattern (Sift pattern)

The component Sift Pattern

Sift Pattern (Sift)
Sets  >  List  >  Sift Pattern
Sift elements in a list using a repeating index pattern.
Inputs
List (L)List to sift
Sift Pattern (P)Sifting pattern
Outputs
Output 0 (0)Output for sift index 0
Output 1 (1)Output for sift index 1
is similar to Dispatch but its pattern P is not made with Booleans (0 and 1) but with integers. The items at input L will be passed to the output that corresponds with the provided integer. The ZUI can be used to add outputs. Instead of just forwarding the items exclusively to the corresponding list, their index at the other lists is filled with null items.

### Remove null items

The simplest way to remove all null items from a list, is to use Clean Tree

Clean Tree (Clean)
Sets  >  Tree  >  Clean Tree
Removed all null and invalid items from a data tree.
Inputs
Remove Nulls (N)Remove null items from the tree.
Remove Invalid (X)Remove invalid items from the tree.
Remove Empty (E)Remove empty branches from the tree.
Tree (T)Data tree to clean
Outputs
Tree (T)Spotless data tree
. See Clean Tree
for more information. Input N (Remove Nulls) is set to True by default.

Another possibility is to use Null Item

Null Item (Null)
Sets  >  List  >  Null Item
Test a data item for null or invalidity
Inputs
Item (I)Item to test
Outputs
Null Flags (N)True if item is Null
Invalid Flags (X)True if item is Invalid
Description (D)A textual description of the object state
to find the index of any null item. We can then use Cull Pattern
Cull Pattern (Cull)
Sets  >  Sequence  >  Cull Pattern
Cull (remove) elements in a list using a repeating bit mask.
Inputs
List (L)List to cull
Cull Pattern (P)Culling pattern
Outputs
List (L)Culled list
, on which we Invert input P, to remove all positive matches from a list.

### Group items that share equal properties

For bundling items that share an equal property, we find the components for this operation in the Grasshopper ribbon tab Sets.

For example, if we want to group lines by their length, we can calculate their lengths and use Create Set

Create Set (CSet)
Sets  >  Sets  >  Create Set
Creates the valid set from a list of items (a valid set only contains distinct elements).
Inputs
List (L)List of data.
Outputs
Set (S)A set of all the distincts values in L
Map (M)An index map from original indices to set indices
to compute how many unique values there are. We will then connect output S to a Member Index
Member Index (MIndex)
Sets  >  Sets  >  Member Index
Find the occurences of a specific member in a set.
Inputs
Set (S)Set to operate on.
Member (M)Member to search for.
Outputs
Index (I)Indices of member.
Count (N)Number of occurences of the member.
component, which will retrieve the indices for the items that belong to each unique value. A List Item
List Item (Item)
Sets  >  List  >  List Item
Retrieve a specific item from a list.
Inputs
List (L)Base list
Index (i)Item index
Wrap (W)Wrap index to list bounds
Outputs
Item (i)Item at {i'}
component will then create separate lists for each property.

Another way to receive a similar result is to use output M of Create Set

Create Set (CSet)
Sets  >  Sets  >  Create Set
Creates the valid set from a list of items (a valid set only contains distinct elements).
Inputs
List (L)List of data.
Outputs
Set (S)A set of all the distincts values in L
Map (M)An index map from original indices to set indices
, which returns to which new index the original item was remapped. We can then use Sift Pattern
Sift Pattern (Sift)
Sets  >  List  >  Sift Pattern
Sift elements in a list using a repeating index pattern.
Inputs
List (L)List to sift
Sift Pattern (P)Sifting pattern
Outputs
Output 0 (0)Output for sift index 0
Output 1 (1)Output for sift index 1
to generate lists that share the same property each. The generated lists will have null items.

This page is open source. Edit it on GitHub or see how you can contribute.