luoma 0.1.0

data/docs/filter_reference.md

@@ -0,0 +1,1702 @@
+# Built-in filters
+
+!!! warning
+
+    This page is a work in progress. Some of the information here is not accurate.
+
+## abs
+
+```
+<number> | abs
+```
+
+Return the absolute value of a number. Works on integers, floats and string representations of integers or floats.
+
+```liquid2
+{{ -42 | abs }}
+{{ 7.5 | abs }}
+{{ '42.0' | abs }}
+```
+
+```plain title="output"
+42
+7.5
+42.0
+```
+
+Given a value that can't be cast to an integer or float, the special value `Nothing` will be returned.
+
+```liquid2
+{{ 'hello' | abs }}
+{{ 'hello' | abs or 0 }}
+{{ ('hello' | abs) or 99 }}
+```
+
+```plain title="output"
+
+0
+```
+
+## append
+
+```
+<string> | append: <string>
+```
+
+Return the input value concatenated with the argument value.
+
+```liquid2
+{{ 'Hello, ' | append: 'World!' }}
+```
+
+```plain title="output"
+Hello, World!
+```
+
+If either the input value or argument are not a string, they will be coerced to a string before concatenation.
+
+```liquid2
+{% assign a_number = 7.5 -%}
+{{ 42 | append: a_number }}
+{{ nosuchthing | append: 'World!' }}
+```
+
+```plain title="output"
+427.5
+World!
+```
+
+## at_least
+
+```
+<number> | at_least: <number>
+```
+
+Return the maximum of the filter's input value and its argument. If either input value or argument are string representations of an integer or float, they will be cast to an integer or float prior to comparison.
+
+```liquid2
+{{ -5.1 | at_least: 8 }}
+{{ 8 | at_least: '5' }}
+```
+
+```plain title="output"
+8
+8
+```
+
+If both input value and argument can not be cast to an integer or float, the special value `Nothing` will be returned instead.
+
+```liquid2
+{{ "hello" | at_least: 2 }}
+{{ "hello" | at_least: -2 }}
+{{ -1 | at_least: "abc" }}
+{{ ('foo' | at_least: "bar") or 42 }}
+```
+
+```plain title="output"
+2
+-2
+-1
+42
+```
+
+## at_most
+
+```
+<number> | at_most: <number>
+```
+
+Return the minimum of the filter's input value and its argument. If either input value or argument are string representations of an integer or float, they will be cast to an integer or float prior to comparison.
+
+```liquid2
+{{ 5 | at_most: 8 }}
+{{ '8' | at_most: 5 }}
+```
+
+```plain title="output"
+5
+5
+```
+
+If both input value and argument can not be cast to an integer or float, the special value `Nothing` will be returned instead.
+
+```liquid2
+{{ "hello" | at_most: 2 }}
+{{ "hello" | at_most: -2 }}
+{{ -1 | at_most: "abc" }}
+{{ ('foo' | at_most: "bar") or 42 }}
+```
+
+```plain title="output"
+2
+2
+-1
+42
+```
+
+## capitalize
+
+```
+<string> | capitalize
+```
+
+Return the input string with the first character in upper case and the rest lowercase.
+
+```liquid2
+{{ 'heLLO, World!' | capitalize }}
+```
+
+```plain title="output"
+Hello, world!
+```
+
+If the input value is not a string, it will be converted to a string.
+
+```liquid2
+{{ 42 | capitalize }}
+```
+
+```plain title="output"
+42
+```
+
+## ceil
+
+```
+<number> | ceil
+```
+
+Round the input value up to the nearest whole number. The input value will be converted to a number if it is not an integer or float.
+
+```liquid2
+{{ 5.1 | ceil }}
+{{ 5.0 | ceil }}
+{{ 5 | ceil }}
+{{ '5.4' | ceil }}
+```
+
+```plain title="output"
+6
+5
+5
+5
+```
+
+If the input is undefined or can't be converted to a number, the special value `Nothing` is returned.
+
+```liquid2
+{{ 'hello' | ceil }}
+{{ ('hello' | ceil) or 1 }}
+```
+
+```plain title="output"
+
+1
+```
+
+## compact
+
+```
+<array> | compact[: <key>]
+```
+
+Return a new array containing items from the input array excluding `null` and `Nothing` values.
+
+```liquid2
+{%- assign a = [1, 2, null, nosuchthing ] -%}
+{{ a | compact }}
+```
+
+```title="Output"
+[1,2]
+```
+
+If `key` is given and it is a string, array items should be objects and the key is used to lookup a property of each object.
+
+```liquid2
+{%- assign
+  items = [
+    { "title": "foo", "id": 1 },
+    { "title": null, "id": 2 },
+    { "title": "baz", "id": 3 },
+  ]
+-%}
+
+{{ items | compact: "title" }}
+```
+
+```title="Output"
+[{"title":"foo","id":1},{"title":"baz","id":3}]
+```
+
+If `key` is a lambda expression, the expression is evaluated for each item in the input array. If the expression evaluates to `nil` or `Nothing`, the item is excluded from the result.
+
+```liquid2
+{%- assign
+  items = [
+    { "title": "foo", "id": 1 },
+    { "id": null },
+    { "title": null, "id": 3 },
+  ]
+-%}
+
+{{ items | compact: x -> (x.title or x.id) }}
+```
+
+```title="Output"
+[{"title":"foo","id":1},{"title":null,"id":3}]
+```
+
+## concat
+
+```
+<array> | concat: <array>
+```
+
+Create a new array by joining one array-like object with another.
+
+```liquid2
+{% assign fruits = "apples, oranges, peaches" | split: ", " %}
+{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
+
+{% assign everything = fruits | concat: vegetables %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+```plain title="output"
+- apples
+- oranges
+- peaches
+- carrots
+- turnips
+- potatoes
+```
+
+If the input value is not array-like, it will be converted to an array. No conversion is attempted for the argument value.
+
+```liquid2
+{% assign fruits = "apples, oranges, peaches" | split: ", " -%}
+{% assign things = "hello" | concat: fruits -%}
+
+{% for item in things -%}
+- {{ item }}
+{% endfor %}
+```
+
+```plain title="output"
+- h
+- e
+- l
+- l
+- o
+- apples
+- oranges
+- peaches
+```
+
+If the input is a nested array, it will be flattened before concatenation. The argument is not flattened.
+
+```json title="data"
+{
+  "a": [
+    ["a", "x"],
+    ["b", ["y", ["z"]]]
+  ],
+  "b": ["c", "d"]
+}
+```
+
+```liquid2
+{{ a | concat: b | join: '#' }}
+```
+
+```plain title="output"
+a#x#b#y#z#c#d
+```
+
+## date
+
+```
+<datetime> | date: <string>
+```
+
+Format a date and/or time according the the given format string. The input can be a string, in which case the string will be parsed as a date/time before formatting.
+
+:::caution
+
+LiquidScript's `date` filter can parse Unix timestamps, ISO 8601, RFC2822, SQL and HTTP header formatted date/time strings. It does not do fuzzy parsing like Ruby or Python Liquid.
+
+:::
+
+```liquid2
+{{ "March 14, 2016" | date: "%b %d, %y" }}
+```
+
+```plain title="output"
+Mar 14, 16
+```
+
+The special `'now'` or `'today'` input values can be used to get the current timestamp. `'today'` is an alias for `'now'`. Both include time information.
+
+```liquid2
+{{ "now" | date: "%Y-%m-%d %H:%M" }}
+```
+
+```plain title="output"
+2021-12-02 10:17
+```
+
+If the input is undefined, an empty string is returned.
+
+```liquid2
+{{ nosuchthing | date: "%Y-%m-%d %H:%M" }}
+```
+
+```plain title="output"
+
+```
+
+## default
+
+```
+<expression> | default[: <object>[, allow_false:<bool>]]
+```
+
+Return a default value if the input is undefined, `nil`/`null`, `false` or empty, or return the input unchanged otherwise.
+
+```liquid2
+{{ product_price | default: 2.99 }}
+
+{%- assign product_price = "" %}
+{{ product_price | default: 2.99 }}
+
+{%- assign product_price = 4.99 %}
+{{ product_price | default: 2.99 }}
+```
+
+```plain title="output"
+2.99
+2.99
+4.99
+```
+
+If the optional `allow_false` argument is `true`, an input of `false` will not return the default. `allow_false` defaults to `false`.
+
+```liquid2
+{% assign product_reduced = false -%}
+{{ product_reduced | default: true, allow_false: true }}
+```
+
+```plain title="output"
+false
+```
+
+If no argument is given, the default value will be an empty string.
+
+```liquid2
+{{ product_price | default }}
+```
+
+```plain title="output"
+
+```
+
+Empty strings, arrays and objects all cause the default value to be returned. `0` does not.
+
+```liquid2
+{{ "" | default: "hello" }}
+{{ 0 | default: 99 }}
+```
+
+```plain title="output"
+hello
+0
+```
+
+## divided_by
+
+```
+<number> | divided_by: <number>
+```
+
+Divide a number by another number. The result is rounded down to the nearest integer if the divisor is an integer.
+
+```liquid2
+{{ 16 | divided_by: 4 }}
+{{ 5 | divided_by: 3 }}
+```
+
+```plain title="output"
+4
+1
+```
+
+If you divide by a float, the result will be a float.
+
+```liquid2
+{{ 20 | divided_by: 7 }}
+{{ 20 | divided_by: 7.0 }}
+```
+
+```plain title="output"
+2
+2.857142857142857
+```
+
+If either the input or argument are not an integer or float, Liquid will try to convert them to an integer or float. If the input can't be converted, `0` will be used instead. If the argument can't be converted, an exception is raised.
+
+```liquid2
+{{ "20" | divided_by: "7" }}
+{{ "hello" | divided_by: 2 }}
+```
+
+```plain title="output"
+2
+0
+```
+
+## downcase
+
+```
+<string> | downcase
+```
+
+Return the input string with all characters in lowercase.
+
+```liquid2
+{{ 'Hello, World!' | downcase }}
+```
+
+```plain title="output"
+hello, world!
+```
+
+If the input is not a string, Liquid will convert it to a string before forcing characters to lowercase.
+
+```liquid2
+{{ 5 | downcase }}
+```
+
+```plain title="output"
+5
+```
+
+If the input is undefined, an empty string is returned.
+
+## escape
+
+```
+<string> | escape
+```
+
+Escape special characters in a string for safe use in HTML.
+
+This filter replaces the characters `&`, `<`, `>`, `'`, and `"` with their corresponding HTML-safe sequences:
+
+- `&` -> `&amp;`
+- `<` -> `&lt;`
+- `>` -> `&gt;`
+- `'` -> `&#39;`
+- `"` -> `&#34;`
+
+This helps prevent HTML injection when rendering untrusted content in HTML element bodies or attributes.
+
+:::caution
+
+This filter does **not** make strings safe for use in JavaScript, including in `<script>` blocks, inline event handler attributes (e.g. `onerror`), or other JavaScript contexts. For those cases, use the [`escapejs`](#escapejs) filter instead.
+
+:::
+
+```liquid2
+{{ "Have you read 'James & the Giant Peach'?" | escape }}
+```
+
+```plain title="output"
+Have you read &#39;James &amp; the Giant Peach&#39;?
+```
+
+## escapejs
+
+```
+<string> | escapejs
+```
+
+Escape characters for safe use in JavaScript string literals.
+
+This filter escapes a string for embedding inside **JavaScript string literals**, using either single or double quotes (e.g. `'...'` or `"..."`). It replaces control characters and potentially dangerous symbols with their corresponding Unicode escape sequences.
+
+Escaped characters include:
+
+- ASCII control characters (U+0000 to U+001F)
+- Characters like quotes, angle brackets, ampersands, equals signs - Line/paragraph separators (U+2028, U+2029)
+
+:::caution
+
+This filter does **not** make strings safe for use in JavaScript template literals (backtick strings), or in raw JavaScript expressions. Use it only when placing data inside quoted JS strings within inline `<script>` blocks or event handlers.
+
+**Recommended alternatives:**
+
+- Pass data using HTML `data-*` attributes and read them in JS via `element.dataset`.
+- For structured data, prefer a JSON-serialization approach using a JSON filter.
+
+:::
+
+```liquid2
+{% assign some_string = "<script>alert('x')</script>" %}
+<img src="" onerror="{{ some_string | escapejs }}" />
+```
+
+```plain title="output"
+<img src="" onerror="\u003Cscript\u003Ealert(\u0027x\u0027)\u003C/script\u003E" />
+```
+
+## escape_once
+
+```
+<string> | escape_once
+```
+
+Escape a string for HTML, but avoid double-escaping existing entities.
+
+Converts characters like `&`, `<`, and `>` to their HTML-safe sequences, but leaves existing HTML entities untouched (e.g., `&amp;` stays `&amp;`).
+
+This is useful when escaping content that may already be partially escaped.
+
+See the [`escape`](#escape) filter for details and limitations.
+
+```liquid2
+{{ "Have you read 'James &amp; the Giant Peach'?" | escape_once }}
+```
+
+```plain title="output"
+Have you read &#39;James &amp; the Giant Peach&#39;?
+```
+
+## find
+
+```
+<array> | find: <string>[, <object>]
+```
+
+Return the first item in the input array that contains a property, given as the first argument, equal to the value given as the second argument. If no such item exists, `null` is returned.
+
+In this example we select the first page in the "Programming" category.
+
+```json title="data"
+{
+  "pages": [
+    {
+      "id": 1,
+      "title": "Introduction to Cooking",
+      "category": "Cooking",
+      "tags": ["recipes", "beginner", "cooking techniques"]
+    },
+    {
+      "id": 2,
+      "title": "Top 10 Travel Destinations in Europe",
+      "category": "Travel",
+      "tags": ["Europe", "destinations", "travel tips"]
+    },
+    {
+      "id": 3,
+      "title": "Mastering JavaScript",
+      "category": "Programming",
+      "tags": ["JavaScript", "web development", "coding"]
+    }
+  ]
+}
+```
+
+```liquid2
+{% assign page = pages | find: 'category', 'Programming' %}
+{{ page.title }}
+```
+
+```plain title="output"
+Mastering JavaScript
+```
+
+## find_index
+
+Return the index of the first item in the input array that contains a property, given as the first argument, equal to the value given as the second argument. If no such item exists, `null` is returned.
+
+In this example we find the index for the first page in the "Programming" category.
+
+```json title="data"
+{
+  "pages": [
+    {
+      "id": 1,
+      "title": "Introduction to Cooking",
+      "category": "Cooking",
+      "tags": ["recipes", "beginner", "cooking techniques"]
+    },
+    {
+      "id": 2,
+      "title": "Top 10 Travel Destinations in Europe",
+      "category": "Travel",
+      "tags": ["Europe", "destinations", "travel tips"]
+    },
+    {
+      "id": 3,
+      "title": "Mastering JavaScript",
+      "category": "Programming",
+      "tags": ["JavaScript", "web development", "coding"]
+    }
+  ]
+}
+```
+
+```liquid2
+{% assign index = pages | find_index: 'category', 'Programming' %}
+{{ pages[index].title }}
+```
+
+```plain title="output"
+Mastering JavaScript
+```
+
+## first
+
+```
+<sequence> | first
+```
+
+Return the first item of the input sequence. The input could be array-like or a mapping, but not a string.
+
+```liquid2
+{{ "Ground control to Major Tom." | split: " " | first }}
+```
+
+```plain title="output"
+Ground
+```
+
+If the input sequence is undefined, empty or not a sequence, `nil` is returned.
+
+## floor
+
+```
+<number> | floor
+```
+
+Return the input down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.
+
+```liquid2
+{{ 1.2 | floor }}
+{{ 2.0 | floor }}
+{{ 183.357 | floor }}
+{{ -5.4 | floor }}
+{{ "3.5" | floor }}
+```
+
+```plain title="output"
+1
+2
+183
+-6
+3
+```
+
+If the input can't be converted to a number, `0` is returned.
+
+## has
+
+```
+<array> | has: <string>[, <object>]
+```
+
+Return `true` if the input array contains an object with a property identified by the first argument that is equal to the object given as the second argument. `false` is returned if none of the items in the input array contain such a property/value.
+
+In this example we test to see if any pages are in the "Programming" category.
+
+```json title="data"
+{
+  "pages": [
+    {
+      "id": 1,
+      "title": "Introduction to Cooking",
+      "category": "Cooking",
+      "tags": ["recipes", "beginner", "cooking techniques"]
+    },
+    {
+      "id": 2,
+      "title": "Top 10 Travel Destinations in Europe",
+      "category": "Travel",
+      "tags": ["Europe", "destinations", "travel tips"]
+    },
+    {
+      "id": 3,
+      "title": "Mastering JavaScript",
+      "category": "Programming",
+      "tags": ["JavaScript", "web development", "coding"]
+    }
+  ]
+}
+```
+
+```liquid2
+{% assign has_programming_page = pages | has: 'category', 'Programming' %}
+{{ has_programming_page }}
+```
+
+```plain title="output"
+true
+```
+
+## join
+
+```
+<array> | join[: <string>]
+```
+
+Return the items in the input array as a single string, separated by the argument string. If the
+input is not an array, Liquid will convert it to one. If input array items are not strings, they
+will be converted to strings before joining.
+
+```liquid2
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
+
+{{ beatles | join: " and " }}
+```
+
+```plain title="output"
+John and Paul and George and Ringo
+```
+
+If an argument string is not given, it defaults to a single space.
+
+```liquid2
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
+
+{{ beatles | join }}
+```
+
+```plain title="output"
+John Paul George Ringo
+```
+
+## last
+
+```
+<array> | last
+```
+
+Return the last item in the array-like input.
+
+```liquid2
+{{ "Ground control to Major Tom." | split: " " | last }}
+```
+
+```plain title="output"
+Tom.
+```
+
+If the input is undefined, empty, string or a number, `nil` will be returned.
+
+## lstrip
+
+```
+<string> | lstrip
+```
+
+Return the input string with all leading whitespace removed. If the input is not a string, it will
+be converted to a string before stripping whitespace.
+
+```liquid2
+{{ "          So much room for activities          " | lstrip }}!
+```
+
+```plain title="output"
+So much room for activities          !
+```
+
+## map
+
+```
+<array> | map: <string | lambda expression>
+```
+
+Extract properties from an array of objects into a new array.
+
+For example, if `pages` is an array of objects with a `category` property:
+
+```json title="data"
+{
+  "pages": [
+    { "category": "business" },
+    { "category": "celebrities" },
+    { "category": "lifestyle" },
+    { "category": "sports" },
+    { "category": "technology" }
+  ]
+}
+```
+
+```liquid2
+{% assign categories = pages | map: "category" -%}
+
+{% for category in categories -%}
+- {{ category }}
+{%- endfor %}
+```
+
+```plain title="output"
+- business
+- celebrities
+- lifestyle
+- sports
+- technology
+```
+
+## minus
+
+```
+<number> | minus: <number>
+```
+
+Return the result of subtracting one number from another. If either the input or argument are not a number, Liquid will try to convert them to a number. If that conversion fails, `0` is used instead.
+
+```liquid2
+{{ 4 | minus: 2 }}
+{{ "16" | minus: 4 }}
+{{ 183.357 | minus: 12.2 }}
+{{ "hello" | minus: 10 }}
+```
+
+```plain title="output"
+2
+12
+171.157
+-10
+```
+
+## modulo
+
+```
+<number> | modulo: <number>
+```
+
+Return the remainder from the division of the input by the argument.
+
+```liquid2
+{{ 3 | modulo: 2 }}
+{{ "24" | modulo: "7" }}
+{{ 183.357 | modulo: 12 }}
+```
+
+```plain title="output"
+1
+3
+3.357
+```
+
+If either the input or argument are not an integer or float, Liquid will try to convert them to an
+integer or float. If the input can't be converted, `0` will be used instead. If the argument can't
+be converted, an exception is raised.
+
+## newline_to_br
+
+```
+<string> | newline_to_br
+```
+
+Return the input string with `\n` and `\r\n` replaced with `<br />\n`.
+
+```liquid2
+{% capture string_with_newlines %}
+Hello
+there
+{% endcapture %}
+
+{{ string_with_newlines | newline_to_br }}
+```
+
+```plain title="output"
+
+
+<br />
+Hello<br />
+there<br />
+
+```
+
+## plus
+
+```
+<number> | plus: <number>
+```
+
+Return the result of adding one number to another. If either the input or argument are not a number, Liquid will try to convert them to a number. If that conversion fails, `0` is used instead.
+
+```liquid2
+{{ 4 | plus: 2 }}
+{{ "16" | plus: "4" }}
+{{ 183.357 | plus: 12 }}
+```
+
+```plain title="output"
+6
+20
+195.357
+```
+
+## prepend
+
+```
+<string> | prepend: <string>
+```
+
+Return the argument concatenated with the filter input.
+
+```liquid2
+{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}
+```
+
+```plain title="output"
+Some fruit: apples, oranges, and bananas
+```
+
+If either the input value or argument are not a string, they will be coerced to a string before
+concatenation.
+
+```liquid2
+{% assign a_number = 7.5 -%}
+{{ 42 | prepend: a_number }}
+{{ nosuchthing | prepend: 'World!' }}
+```
+
+```plain title="output"
+7.542
+World!
+```
+
+## reject
+
+```
+<array> | reject: <string>[, <object>]
+```
+
+Return a copy of the input array including only those objects that have a property, named with the first argument, **that is not equal to** a value, given as the second argument. If a second argument is not given, only elements with the named property that are falsy will be included.
+
+```json title="data"
+{
+  "products": [
+    { "title": "Vacuum", "type": "house", "available": true },
+    { "title": "Spatula", "type": "kitchen", "available": false },
+    { "title": "Television", "type": "lounge", "available": true },
+    { "title": "Garlic press", "type": "kitchen", "available": true }
+  ]
+}
+```
+
+```liquid2
+All products:
+{% for product in products -%}
+- {{ product.title }}
+{% endfor %}
+
+{%- assign kitchen_products = products | reject: "type", "kitchen" -%}
+
+Non kitchen products:
+{% for product in kitchen_products -%}
+- {{ product.title }}
+{% endfor %}
+
+{%- assign unavailable_products = products | reject: "available" -%}
+
+Unavailable products:
+{% for product in unavailable_products -%}
+- {{ product.title }}
+{% endfor %}
+```
+
+```plain title="output"
+All products:
+- Vacuum
+- Spatula
+- Television
+- Garlic press
+Non kitchen products:
+- Vacuum
+- Television
+Unavailable products:
+- Spatula
+```
+
+## remove
+
+```
+<string> | remove: <string>
+```
+
+Return the input with all occurrences of the argument string removed.
+
+```liquid2
+{{ "I strained to see the train through the rain" | remove: "rain" }}
+```
+
+```plain title="output"
+I sted to see the t through the
+```
+
+If either the filter input or argument are not a string, they will be coerced to a string before
+substring removal.
+
+## remove_first
+
+```
+<string> | remove_first: <string>
+```
+
+Return a copy of the input string with the first occurrence of the argument string removed.
+
+```liquid2
+{{ "I strained to see the train through the rain" | remove_first: "rain" }}
+```
+
+```plain title="output"
+I sted to see the train through the rain
+```
+
+If either the filter input or argument are not a string, they will be coerced to a string before substring removal.
+
+## remove_last
+
+```
+<string> | remove_last: <string>
+```
+
+Return a copy of the input string with the last occurrence of the argument string removed.
+
+```liquid2
+{{ "I strained to see the train through the rain" | remove_last: "rain" }}
+```
+
+```plain title="output"
+I strained to see the train through the
+```
+
+If either the filter input or argument are not a string, they will be coerced to a string before substring removal.
+
+## replace
+
+```
+<string> | replace: <string>[, <string>]
+```
+
+Return the input with all occurrences of the first argument replaced with the second argument. If
+the second argument is omitted, it will default to an empty string, making `replace` behave like
+`remove`.
+
+```liquid2
+{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}
+```
+
+```plain title="output"
+Take your protein pills and put your helmet on
+```
+
+If either the filter input or argument are not a string, they will be coerced to a string before
+replacement.
+
+## replace_first
+
+```
+<string> | replace_first: <string>[, <string>]
+```
+
+Return a copy of the input string with the first occurrence of the first argument replaced with the second argument. If the second argument is omitted, it will default to an empty string, making `replace_first` behave like `remove_first`.
+
+```liquid2
+{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}
+```
+
+```plain title="output"
+Take your protein pills and put my helmet on
+```
+
+If either the filter input or argument are not a string, they will be coerced to a string before replacement.
+
+## replace_last
+
+```
+<string> | replace_last: <string>, <string>
+```
+
+Return a copy of the input string with the last occurrence of the first argument replaced with the second argument.
+
+```liquid2
+{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}
+```
+
+```plain title="output"
+Take my protein pills and put your helmet on
+```
+
+If either the filter input or argument are not a string, they will be coerced to a string before replacement.
+
+## reverse
+
+```
+<array> | reverse
+```
+
+Return a copy of the input array with the items in reverse order. If the filter input is a string, `reverse` will return the string unchanged.
+
+```liquid2
+{% assign my_array = "apples, oranges, peaches, plums" | split: ", " -%}
+
+{{ my_array | reverse | join: ", " }}
+```
+
+```plain title="output"
+plums, peaches, oranges, apples
+```
+
+## round
+
+```
+<number> | round[: <number>]
+```
+
+Return the input number rounded to the given number of decimal places. The number of digits defaults to `0`.
+
+```liquid2
+{{ 1.2 | round }}
+{{ 2.7 | round }}
+{{ 183.357 | round: 2 }}
+```
+
+```plain title="output"
+1
+3
+183.36
+```
+
+If either the filter input or its optional argument are not an integer or float, they will be converted to an integer or float before rounding.
+
+## rstrip
+
+```
+<string> | rstrip
+```
+
+Return the input string with all trailing whitespace removed. If the input is not a string, it will be converted to a string before stripping whitespace.
+
+```liquid2
+{{ "          So much room for activities          " | rstrip }}!
+```
+
+```plain title="output"
+          So much room for activities!
+```
+
+## safe
+
+```
+<string> | safe
+```
+
+Return the input string marked as safe to use in an HTML or XML document. If the filter input is not a string, it will be converted to an HTML-safe string.
+
+With auto-escape enabled and the following global variables:
+
+```json title="data"
+{
+  "username": "Sally",
+  "greeting": "</p><script>alert('XSS!');</script>"
+}
+```
+
+```liquid2 title="template"
+<p>{{ greeting }}, {{ username }}</p>
+<p>{{ greeting | safe }}, {{ username }}</p>
+```
+
+```html title="output"
+<p>&lt;/p&gt;&lt;script&gt;alert(&#34;XSS!&#34;);&lt;/script&gt;, Sally</p>
+<p></p><script>alert('XSS!');</script>, Sally</p>
+```
+
+## size
+
+```
+<object> | size
+```
+
+Return the size of the input object. Works on strings, arrays and hashes.
+
+```liquid2
+{{ "Ground control to Major Tom." | size }}
+{{ "apples, oranges, peaches, plums" | split: ", " | size }}
+```
+
+```plain title="output"
+28
+4
+```
+
+## slice
+
+```
+<sequence> | slice: <int>[, <int>]
+```
+
+Return a substring or subsequence of the input string or array. The first argument is the zero-based start index. The second, optional argument is the length of the substring or sequence, which defaults to `1`.
+
+```liquid2
+{{ "Liquid" | slice: 0 }}
+{{ "Liquid" | slice: 2 }}
+{{ "Liquid" | slice: 2, 5 }}
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
+{{ beatles | slice: 1, 2 | join: " " }}
+```
+
+```plain title="output"
+L
+q
+quid
+Paul George
+```
+
+If the first argument is negative, the start index is counted from the end of the sequence.
+
+```liquid2
+{{ "Liquid" | slice: -3 }}
+{{ "Liquid" | slice: -3, 2 }}
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
+{{ beatles | slice: -2, 2 | join: " " }}
+```
+
+```plain title="output"
+u
+ui
+George Ringo
+```
+
+## sort
+
+````
+<array> | sort[: <string>]
+``
+
+Return a copy of the input array with its elements sorted.
+
+```liquid
+{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " -%}
+{{ my_array | sort | join: ", " }}
+````
+
+```plain title="output"
+Sally Snake, giraffe, octopus, zebra
+```
+
+The optional argument is a sort key. If given, it should be the name of a property and the filter's input should be an array of objects.
+
+```json title="data"
+{
+  "collection": {
+    "products": [
+      { "title": "A Shoe", "price": "9.95" },
+      { "title": "A Tie", "price": "0.50" },
+      { "title": "A Hat", "price": "2.50" }
+    ]
+  }
+}
+```
+
+```liquid2 title="template"
+{% assign products_by_price = collection.products | sort: "price" -%}
+{% for product in products_by_price %}
+  <h4>{{ product.title }}</h4>
+{% endfor %}
+```
+
+```plain title="output"
+<h4>A Tie</h4>
+<h4>A Hat</h4>
+<h4>A Shoe</h4>
+```
+
+## sort_natural
+
+```
+<array> | sort_natural[: <string>]
+```
+
+Return a copy of the input array with its elements sorted case-insensitively. Array items will be compared by their string representations, forced to lowercase.
+
+```liquid2
+{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " -%}
+{{ my_array | sort_natural | join: ", " }}
+```
+
+```plain title="output"
+giraffe, octopus, Sally Snake, zebra
+```
+
+The optional argument is a sort key. If given, it should be the name of a property and the filter's input should be an array of objects. Array elements are compared using the lowercase string representation of that property.
+
+```json title="data"
+{
+  "collection": {
+    "products": [
+      { "title": "A Shoe", "company": "Cool Shoes" },
+      { "title": "A Tie", "company": "alpha Ties" },
+      { "title": "A Hat", "company": "Beta Hats" }
+    ]
+  }
+}
+```
+
+```liquid2 title="template"
+{% assign products_by_company = collection.products | sort_natural: "company" %}
+{% for product in products_by_company %}
+  <h4>{{ product.title }}</h4>
+{% endfor %}
+```
+
+```plain title="output"
+<h4>A Tie</h4>
+<h4>A Hat</h4>
+<h4>A Shoe</h4>
+```
+
+## split
+
+```
+<string> | split: <string>
+```
+
+Return an array of strings that are the input string split on the filter's argument string.
+
+```liquid2
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " -%}
+
+{% for member in beatles %}
+  {{- member }}
+{% endfor %}
+```
+
+```plain title="output"
+John
+Paul
+George
+Ringo
+```
+
+If the argument is undefined or an empty string, the input will be split at every character.
+
+```liquid2
+{{ "Hello there" | split: nosuchthing | join: "#" }}
+```
+
+```plain title="output"
+H#e#l#l#o# #t#h#e#r#e
+```
+
+## squish
+
+```
+<string> | squish
+```
+
+Return the input string with all leading and trailing whitespace removed, and any other runs of whitespace replaced with a single space.
+
+```liquid2
+{{ "    Hello, \n\t World! \r\n" | squish }}
+```
+
+```plain title="output"
+Hello, World!
+```
+
+## strip
+
+```
+<string> | strip
+```
+
+Return the input string with all leading and trailing whitespace removed. If the input is not a string, it will be converted to a string before stripping whitespace.
+
+```liquid2
+{{ "          So much room for activities          " | strip }}!
+```
+
+```plain title="output"
+So much room for activities!
+```
+
+## strip_html
+
+```
+<string> | strip_html
+```
+
+Return the input string with all HTML tags removed.
+
+```liquid2
+{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}
+```
+
+```plain title="output"
+Have you read Ulysses?
+```
+
+## strip_newlines
+
+```
+<string> | strip_newlines
+```
+
+Return the input string with `\n` and `\r\n` removed.
+
+```liquid2
+{% capture string_with_newlines %}
+Hello
+there
+{% endcapture -%}
+
+{{ string_with_newlines | strip_newlines }}
+```
+
+```plain title="output"
+Hellothere
+```
+
+## sum
+
+```
+<array> | sum[: <string>]
+```
+
+Return the sum of all numeric elements in an array.
+
+```liquid2
+{% assign array = '1,2,3' | split: ',' -%}
+{{ array | sum }}
+```
+
+```plain title="output"
+6
+```
+
+If the optional string argument is given, it is assumed that array items are hash/dict/mapping-like, and the argument should be the name of a property/key. The values at `array[property]` will be summed.
+
+## times
+
+```
+<number> | times: <number>
+```
+
+Return the product of the input number and the argument. If either the input or argument are not a number, Liquid will try to convert them to a number. If that conversion fails, `0` is used instead.
+
+```liquid2
+{{ 3 | times: 2 }}
+{{ "24" | times: "7" }}
+{{ 183.357 | times: 12 }}
+```
+
+```plain title="output"
+6
+168
+2200.284
+```
+
+## truncate
+
+```
+<string> | truncate[: <integer>[, <string>]]
+```
+
+Return a truncated version of the input string. The first argument, length, defaults to `50`. The second argument defaults to an ellipsis (`...`).
+
+If the length of the input string is less than the given length (first argument), the input string will be truncated to `length` minus the length of the second argument, with the second argument appended.
+
+```liquid2
+{{ "Ground control to Major Tom." | truncate: 20 }}
+{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
+{{ "Ground control to Major Tom." | truncate: 20, "" }}
+```
+
+```plain title="output"
+Ground control to...
+Ground control, and so on
+Ground control to Ma
+```
+
+## truncatewords
+
+```
+<string> | truncatewords[: <integer>[, <string>]]
+```
+
+Return the input string truncated to the specified number of words, with the second argument appended. The number of words (first argument) defaults to `15`. The second argument defaults to an ellipsis (`...`).
+
+If the input string already has fewer than the given number of words, it is returned unchanged.
+
+```liquid2
+{{ "Ground control to Major Tom." | truncatewords: 3 }}
+{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
+{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
+```
+
+```plain title="output"
+Ground control to...
+Ground control to--
+Ground control to
+```
+
+## uniq
+
+```
+<array> | uniq[: <string>]
+```
+
+Return a copy of the input array with duplicate elements removed.
+
+```liquid2
+{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " -%}
+{{ my_array | uniq | join: ", " }}
+```
+
+```plain title="output"
+ants, bugs, bees
+```
+
+If an argument is given, it should be the name of a property and the filter's input should be an array of objects.
+
+```json title="data"
+{
+  "collection": {
+    "products": [
+      { "title": "A Shoe", "company": "Cool Shoes" },
+      { "title": "A Tie", "company": "alpha Ties" },
+      { "title": "Another Tie", "company": "alpha Ties" },
+      { "title": "A Hat", "company": "Beta Hats" }
+    ]
+  }
+}
+```
+
+```liquid2 title="template"
+{% assign one_product_from_each_company = collections.products | uniq: "company" -%}
+{% for product in one_product_from_each_company -%}
+  - product.title
+{% endfor %}
+```
+
+```plain title="output"
+- A Shoe
+- A Tie
+- A Hat
+```
+
+## upcase
+
+```
+<string> | upcase
+```
+
+Return the input string with all characters in uppercase.
+
+```liquid2
+{{ 'Hello, World!' | upcase }}
+```
+
+```plain title="output"
+HELLO, WORLD!
+```
+
+## url_decode
+
+```
+<string> | url_decode
+```
+
+Return the input string with `%xx` escapes replaced with their single-character equivalents. Also replaces `'+'` with `' '`.
+
+```liquid2
+{{ "My+email+address+is+bob%40example.com%21" | url_decode }}
+```
+
+```plain title="output"
+My email address is bob@example.com!
+```
+
+## url_encode
+
+```
+<string> | url_encode
+```
+
+Return the input string with URL reserved characters %-escaped. Also replaces `' '` with `'+'`.
+
+```liquid2
+{{ My email address is bob@example.com! | url_encode }}
+```
+
+```plain title="output"
+My+email+address+is+bob%40example.com%21
+```
+
+## where
+
+```
+<array> | where: <string>[, <object>]
+```
+
+Return a copy of the input array including only those objects that have a property, named with the first argument, equal to a value, given as the second argument. If a second argument is not given, only elements with the named property that are truthy will be included.
+
+```json title="data"
+{
+  "products": [
+    { "title": "Vacuum", "type": "house", "available": true },
+    { "title": "Spatula", "type": "kitchen", "available": false },
+    { "title": "Television", "type": "lounge", "available": true },
+    { "title": "Garlic press", "type": "kitchen", "available": true }
+  ]
+}
+```
+
+```liquid2
+All products:
+{% for product in products -%}
+- {{ product.title }}
+{% endfor %}
+
+{%- assign kitchen_products = products | where: "type", "kitchen" -%}
+
+Kitchen products:
+{% for product in kitchen_products -%}
+- {{ product.title }}
+{% endfor %}
+
+{%- assign available_products = products | where: "available" -%}
+
+Available products:
+{% for product in available_products -%}
+- {{ product.title }}
+{% endfor %}
+```
+
+```plain title="output"
+All products:
+- Vacuum
+- Spatula
+- Television
+- Garlic press
+
+Kitchen products:
+- Spatula
+- Garlic press
+
+Available product:
+- Vacuum
+- Television
+- Garlic press
+```