Module sorting 

Available on crate feature sort only.

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.