Difference between filter and subfilter?

[The Islander]

Hello, after reading the official documentation on subfilter and filter, it's not clear to me what the difference is between these two operators.

• Why would someone choose to use one over the other? A couple of simple examples where one differentiates from the other would be very useful.
• Is subfilter suitable for use in the middle of a filter expression? The subfilter documentation page itself shows an example of a subfilter in the middle of a filter expression, but none of the examples do this
• I'm further confused by the discussion in this issue on Github which is requesting filter as a simple alias of subfilter for readability

On a side note, I thought there would be some consistency to availability of currentTiddler within the operand of filter, but there isn't. Are saqimtiaz's improvements something slated to be included in 5.2.0?

Thanks!

[TW Tones]

The Islander

I agree this should be better documented. To stimulate the discussion;

As the person who submitted that issue on github subfilter and subsequently closed it, the filter operator, and the subsequent :filter run prefix have changed this quite a bit. My concern then was "not having a filter to be sub of when used:, however as the first example show I have effectively gotten what I asked for 

The subfilter was first on the scene, and made imbedding a full filter inside another much easier, otherwise you would have to reconstruct the filter from filter fragments. 

From the doco note it still uses the word subfilter but they look the same.

Filter operator

Apply a subfilter to each input title and return the titles that return a non-empty result from the subfilter  

The filter operator runs a subfilter for each input title, and returns those input titles for which the subfilter returns a non-empty result (in other words the result is not an empty list). The results of the subfilter are thrown away.  

subfilter operator

 select titles from the operand interpreted as a filter expression

 Compare with the similar filter operator which runs a subfilter against each title, returning those titles that return a non-empty list (and discards the results of the subfilter)  

In the following example there is no apparent difference, remember there is an implied [all[].. at the beginning of reach run.

\define active-filter() [!tag[done]!tag[reference]]

{{{ [tag[todo]count[]] }}}

{{{ [tag[todo]subfilter<active-filter>count[]] }}}

{{{ [tag[todo]!subfilter<active-filter>count[]] }}}

<hr>

{{{ [tag[todo]filter<active-filter>count[]] }}}

{{{ [tag[todo]!filter<active-filter>count[]] }}}

Regards

Tones

[Eric Shulman]

Here's a demonstration of the difference:

1) Create three tiddlers named A, B, and C, with text content "this is A", "this is B" and "this is C", respectively.

2) Create a Test tiddler containing:

<$vars F="[get[text]match[this is B]]">

subfilter result 1 is: <$text text={{{ [enlist[A B C]subfilter<F>] }}} /><br>

<$list filter="[enlist[A B C]get[text]match[this is B]]" variable="result">

   subfilter result 2 is: <<result>>

</$list>

filter result 1 is: <$text text={{{ [enlist[A B C]filter<F>] }}} /><br>

<$list filter="[enlist[A B C]]">

   <$list filter="[<currentTiddler>get[text]match[this is B]then<currentTiddler>]" variable="result">

      filter result 2: is <<result>>

   </$list>

</$list>

3) The output will be:

subfilter result 1 is: this is B

subfilter result 2 is: this is B

filter result 1 is: B

filter result 2: is B

The difference:

• subfilter applies filter F to each input title and returns the TEXT that matches "this is B", and is equivalent to inserting filter F into a larger filter expression
• filter applies filter F to each input title and returns the TITLE whose text matches "this is B" and is equivalent to writing nested filters

hope this helps...

-e

[The Islander]

Hi Tones and Eric,

I greatly appreciate your detailed replies! Reading through them clears it up for me thank you.

It may be useful to add this sort of clarification to official documentation - the motivations behind some of the more complex filter operators. If anyone feels it's appropriate for me to request this as an open issue on github, please let me know.

The "filter" filter operator in particular is difficult to search for, due to its identical naming to the parent concept of a filter, and other related naming concepts like the "filter" filter run prefix.

Thanks!