Module row

Available on crate feature row only.

Convert Rust structs with named fields into tables of output

Django produces JSON encoded tabular output in response to queries, where each row of the output is a JSON object, and those objects do not contain any nested objects. Instead, nested objects are represented by a pre-selected foreign key.

Overview

The IntoRow trait in this module allows the type to produce a Serializer that can convert an instance into a row within a table of JSON output. The IntoRow derive macro for this trait will produce everything necessary for structs with named fields.

The value of a cell within the table cannot itself be JSON object-typed, in line with Django’s database origins. However, it is possible to return multiple values in an array inside one cell. The CellValue type captures the subset of permitted JSON Values that are permitted.

A type which can directly be the value in a given cell of output should implement IntoCellValue. If the type implements Display, and if the desired JSON representation is a string, you can derive the marker trait StringCellValue to benefit from a blanket derivation of IntoCellValue for string values. Otherwise IntoCellValue must be implemented directly.

Since Django results do not contain nested objects, fields with structured types must be handled differently. Here, one field of the nested type is chosen to represent that value, as what is in effect a foreign key. The AsForeignKey trait captures this idea, and is blanket implemented for IntoRow types.

Example:

use django_query::row::{Serializer, IntoRow};
use serde_json::json;
use std::sync::Arc;

#[derive(IntoRow)]
struct Foo {
  a: i32,
  #[django(foreign_key="a")]
  b: Option<Arc<Foo>>
}

let f1 = Arc::new(Foo { a: 1, b: None });
let f2 = Arc::new(Foo { a: 2, b: Some(f1.clone()) });
let f3 = Arc::new(Foo { a: 3, b: Some(f2.clone()) });

let ser = Arc::<Foo>::get_serializer();

assert_eq!(ser.to_json(&f1), json! {
  { "a": 1i32, "b": null }
});
assert_eq!(ser.to_json(&f2), json! {
  { "a": 2i32, "b": 1i32 }
});
assert_eq!(ser.to_json(&f3), json! {
  { "a": 3i32, "b": 2i32 }
});

Enums

CellValue

The JSON types Django permits in cells - everything except object.

Traits

AsForeignKey

Convert a structured value into a single representative CellValue

AsForeignKeyWithContext

Convert a structured value into a single representative CellValue using a context value

CellVisitor

Visit the values in the Django output row for a given value.

ColumnVisitor

Visit the columns that a Django output row for a given type will contain.

IntoCellValue

Convert a value into a JSON CellValue.

IntoRow

Produce a Serializer to convert values of this type into rows of output.

IntoRowWithContext

Produce a Serializer to convert values of this type, which requires a context value, into rows of output.

Serializer

A converter that visits rows of Django output for a given type.

StringCellValue

Use Display to convert the type into a CellValue

Derive Macros

IntoRow

Derive the IntoRow trait, determining the display of nested objects.

IntoRowWithPersianRugpersian-rug

Derive the IntoRowWithContext trait for persian-rug types.