FILTER <Name="filter name"> [<Reverse=Yes|No>] [<Join=None|or|and|xor|andnot|ornot|xornot>]
The FILTER command enables you to select and apply a saved filter.
Name = The saved filter name.
Reverse = This parameter is now deprecated, but left in for backwards compatibility. This parameter was added before the option was enabled in the GUI and saved settings. So if your saved filter already has the reverse option ticked, this option has no effect and will [B]not[/B] reverse/negate it. Yes - To invert/reverse the filter (That is, give you all the waypoints that do not match your selection criteria). No - do not reverse. The default value is No
Join = Action to perform with the current filter. The default of "none" meaning the Filter command does not do any "joining" and behaves exactly the same as setting a new filter. Any other value will compare the current filter against this filter using the "join" type and produce a new subset/filter (which will then become the current filter and you can do another "join" and so forth). See notes at end for a full explanation of Join.
Note: If the filter does not return any waypoints it will automatically be cancelled and your subset will contain all waypoints. You can test for this situation using the $_FilterCount system variable. For example:
FILTER Name="User Flagged"
IF $_FilterCount > 0
... do some action
ELSE
PAUSE Msg="No waypoints in filter, action cancelled"
ENDIF
Summary
Join notes
This matrix represents the results of applying the corresponding "bitwise" operation. Read 1 as meaning the waypoint satisfies the condition of the filter and 0 meaning it does not.
AND
Current Filter 0 1 0 1
AND filter 1 1 0 0
Result 0 1 0 0
OR
Current Filter 0 1 0 1
OR Filter 1 1 0 0
Result 1 1 0 1
XOR
Current Filter 0 1 0 1
XOR Filter 1 1 0 0
Result 1 0 0 1
ANDNOT
Current Filter 0 1 0 1
ANDNOT Filter 1 1 0 0
Result 1 0 1 1
ORNOT
Current Filter 0 1 0 1
ORNOT Filter 1 1 0 0
Result 0 0 1 0
XORNOT
Current Filter 0 1 0 1
XORNOT Filter 1 1 0 0
Result 0 1 1 0
Another explanation that some may find easier to understand:
AND - Resulting waypoints exists in both filters (intersection)
OR - Resulting waypoints exists in either filter (union)
XOR - Resulting waypoints must exist in one filter or the other, but not both
ANDNOT - Resulting waypoints include all waypoints except those in both filters
ORNOT - Resulting waypoints only if not in both filters
XORNOT - Resulting waypoints included in both filters, or excluded in both filters. That is, if only one and only one filter condition is met then the waypoint is excluded.
For those that prefer a graphical overview take the following example:
"Found Caches" and "Traditionals" are 2 stored filters, which are joined together with one of the available joining operators.
Macro code in GSAK would be
FILTER Name="Found Caches"
FILTER Name="Traditionals" Join="and | or | xor | andnot | ornot | xornot"
Note that ANDNOT, ORNOT and XORNOT will result in caches
that are not part of the both stored filters.
While joining, you can specify to REVERSE the second condition.
Macro code in GSAK would be
FILTER Name="Found Caches"
FILTER Name="Traditionals" Reverse=Yes Join="and | or | xor | andnot | ornot | xornot"
By using multiple Filter commands with the join parameter you are not limited to just 2 filters. For example, to find waypoints that exist in all three filters:
Filter Name=Filter1
Filter Name=Filter2 Join=and
Filter Name=Filter3 Join=and
If $_FilterCount = 0
Pause Msg="Bummer, no waypoints that match all 3 filters"
EndIf
Note1: The current filter (or any joined filter) may have initially returned zero records. However, the current default behaviour in GSAK is to clear the filter and return the full sub set of caches. When using the "join" parameter, GSAK respects the initial result of the filter (zero records) when it does the join operation. Like normal filters you can always test the final result using the $_FilterCount system variable.
Note2: Because of the complexity of a "joined" filter, the resulting filter is "static" (similar behaviour to setting colours with the COLOR command). That means if you change any waypoints in your "joined filter" you must run the same sequence of "join" filters to determine which waypoints should logically now be in your filter.
Summary