Module sorting

Available on crate feature sort only.

Expand description

§Create sort orders for Rust objects from query URLs

Django queries can contain an ordering expression, which gives the fields of the object that should be used to determine the relative position of objects in the result table. Not all fields are sortable, but each sortable field provides one natural ordering.

For fields of structured type, the natural ordering by that field can be taken from the natural ordering of one of its own fields, but this relationship is fixed. This is the only form of nesting present in ordering expressions.

The expressions themselves are a comma-separated list of fields in priority order. Each field can be optional prefixed with a - to indicate the reverse ordering. So for example "ordering=a,-b", means sort by the a field, and for ties use the reverse ordering of the b field

§Overview

The main trait in this module is Sortable which has an associated derive macro Sortable. Deriving Sortable means the type can describe the sort orders it supports. An OrderingSet can be constructed for any Sortable type, and can parse ordering expressions from django-style queries.

Example:

use django_query::sorting::{Sortable, OrderingSet};

#[derive(Sortable)]
struct Bar {
  #[django(sort)]
  a: i32,
  #[django(sort)]
  b: i32,
}

#[derive(Sortable)]
struct Foo {
  #[django(sort)]
  c: i32,
  #[django(sort("b"))]
  d: Bar,
}

let mut foos = vec![
    Foo { c: 0, d: Bar { a: 1, b: 1 } },
    Foo { c: 1, d: Bar { a: 0, b: 0 } },
    Foo { c: 2, d: Bar { a: 2, b: 1 } },
    Foo { c: 3, d: Bar { a: 3, b: 0 } },
];

let qr = OrderingSet::<Foo>::new();

let sort = qr.create_sort("-c").unwrap();
sort.sort_vec(&mut foos);
assert_eq!(foos[0].c, 3);
assert_eq!(foos[1].c, 2);
assert_eq!(foos[2].c, 1);
assert_eq!(foos[3].c, 0);

let sort = qr.create_sort("d,c").unwrap();
sort.sort_vec(&mut foos);
assert_eq!(foos[0].c, 1);
assert_eq!(foos[1].c, 3);
assert_eq!(foos[2].c, 0);
assert_eq!(foos[3].c, 2);

Because Sorter objects produced by parsing are boxed, there is virtual function call overhead when using them. This can be minimised by using the provided sort_vec method to sort an entire Vec at a time, instead of testing pairs individually with compare.

Structs§

Compare: A Sorter defined for all types that are Ord.
CompareClass: The SorterClass for Compare and ReverseCompare.
OrderingSet: A collection of sort orders, built from a Sortable type.
OrderingSetWithContext: A collection of sort orders, built from a SortableWithContext type.
ReverseCompare: A Sorter defined for all types that are Ord, which reverses the natural order.

Enums§

SorterError: Errors produced by sorting.

Traits§

Accessor: Return a particular member of an instance by reference.
Field: Apply a Sorter to a member of a type.
Meta: Metadata about sorting for a type.
ReferenceField: A marker for an Accessor that can act as a field.
SortVisitor: Receive descriptions of the sort orders a type provides.
Sortable: Something that can describe its sort orders.
SortableWithContext: Something that can describe its sort orders, if a context value is provided.
Sorter: Compare two values of another type R.
SorterClass: Make a type-elided Sorter.
SorterTypedClass: Make a typed Sorter.

Derive Macros§

Sortable: Derive the Sortable trait, creating suitable SorterClass types.
SortableWithPersianRugpersian-rug: Derive the SortableWithContext trait for persian-rug types.