_{Official ZPE/YASS documentation}zpe.lib.sort

Introduction

The zpe.lib.sort plugin provides powerful and flexible sorting functions for lists and maps in ZPE/YASS.

It supports:

• Sorting lists of numbers or strings
• Sorting lists of maps by a specific key
• Sorting map keys
• Sorting map values
• Multiple sorting modes (numeric, string, case-insensitive, natural, and automatic detection)

All sorting functions return a new sorted list. The original list or map is not modified.

Installation

Place zpe.lib.sort.jar in your ZPE native-plugins folder and restart ZPE.

You can also download with the ZULE Package Manager by using:

zpe --zule install zpe.lib.sort.jar

Usage

The most common function is sort, which sorts a list:

import "zpe.lib.sort"

numbers = [5, 2, 10, 1]

sorted = sort(numbers)
print(sorted)

Functions

sort(list items[, string mode][, boolean descending]) ⇒ list

Sorts a list and returns a new sorted list.

Modes:

• "auto" (default) – Automatically detects numeric vs string values.
• "number" – Forces numeric comparison.
• "string" – Case-sensitive string comparison.
• "string_ci" – Case-insensitive string comparison.
• "natural" – Natural sorting (for example: file2 before file10).

If descending is true, the result is reversed.

sort_by(list items, string key[, string mode][, boolean descending]) ⇒ list

Sorts a list of maps by a specified key and returns a new sorted list.

Items without the specified key are placed at the end.

sort_map_keys(map m[, string mode][, boolean descending]) ⇒ list

Returns the keys of a map in sorted order.

sort_map_values(map m[, string mode][, boolean descending]) ⇒ list

Returns the values of a map in sorted order.

Examples

1) Numeric sorting

numbers = [10, 3, 7, 1]

print(sort(numbers, "number"))
print(sort(numbers, "number", true))

2) Case-insensitive string sorting

names = ["ZPE", "apple", "Banana"]

print(sort(names, "string_ci"))

3) Sorting a list of maps

rows = [
  [=>]{"name":"Jamie", "age":34},
  [=>]{"name":"Alice", "age":12},
  [=>]{"name":"Bob", "age":12}
]

sorted = sort_by(rows, "age", "number")
print(sorted)

4) Sorting map keys

m = [=>]{"c":3, "a":1, "b":2}

print(sort_map_keys(m))

Notes and caveats

• All sorting operations are stable. Items with equal values retain their original order.
• The original list or map is not modified. A new sorted list is returned.
• In auto mode, numeric values are sorted numerically and non-numeric values are sorted as strings.
• natural mode is useful for file names and mixed text-number strings (for example: file2 before file10).
• If invalid types are provided, the function may return false.