1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
//! # Diesel Geometry //! //! Diesel Geometry is an extension to Diesel that provides support for geometric types operators. //! If this is your first time with Diesel, we recommend starting with [diesel's getting started //! guide]. They also have [many other long form guides]. //! //! [diesel's getting started guide]: https://diesel.rs/guides/getting-started/ //! [many other long form guides]: https://diesel.rs/guides //! //! # Where to find things //! //! ## Declaring your schema //! //! So Diesel is able to validate your queries at compile time, it requires you to specify your //! schema in your code, which you can do with the `table!` macro from Diesel. //! You cannot use `infer_schema!` with `diesel_geometry` types at this time. //! //! If you use diesel print-schema, you must manually modify the generated code to export the //! `diesel_geometry` sql types inside each `table!` macro that uses diesel_geometry types. Because exporting any types inside the //! table macro overrides the default exports, you must also manually export the diesel sql types //! as well. //! ### Before, as generated by `diesel print-schema` //! //! ```rust //! # static DUMMY: &'static str = r#" //! table! { //! items { //! id -> Integer, //! name -> VarChar, //! location -> Point, //! } //! } //! # "#; //! # fn main() {} //! ``` //! //! ### After manual modification //! ```rust //! # #[macro_use] extern crate diesel; //! # extern crate diesel_geometry; //! table! { //! use diesel::sql_types::*; //! use diesel_geometry::sql_types::*; //! items { //! id -> Integer, //! name -> VarChar, //! location -> Point, //! } //! } //! # fn main() {} //! ``` //! //! ## Getting started //! //! Diesel Geometry provides a [`prelude` module](prelude), which exports most of the typically //! used traits and types. We are conservative about what goes in this module, and avoid anything //! which has a generic name. Files which use Diesel Geometry are expected to have `use //! diesel_geometry::prelude::*;`. //! //! ## Constructing a query //! //! Diesel Geometry extends Diesel in two ways. //! //! - "Expression methods" are things you would call on columns //! or other individual values. //! These methods live in [the `expression_methods` module](expression_methods) //! You can often find these by thinking "what would this be called" //! if it were a method //! and typing that into the search bar //! (e.g. `~=` is called `same_as` in Diesel Geometry). //! Most operators are named based on the Rust function which maps to that //! operator in [`std::ops`][] //! (For example `==` is called `.eq`, and `!=` is called `.ne`). //! - "Bare functions" are normal SQL functions //! such as `isclosed`. //! They live in [the `dsl` module](dsl). //! //! [`std::ops`]: //doc.rust-lang.org/stable/std/ops/index.html //! [`sql_function!`]: macro.sql_function.html //! //! ## Serializing and Deserializing //! //! Diesel Geometry maps "Rust types" (e.g. `(f64, f64)`) to and from "SQL types" //! (e.g. [`diesel_geometry::sql_types::Point`]). //! You can find all the types supported by Diesel Geometry in [the `sql_types` module](sql_types). //! These types are only used to represent a SQL type. //! You should never put them on your `Queryable` structs. //! //! To find all the Rust types which can be used with a given SQL type, //! see the documentation for that SQL type. //! //! [`diesel_geometry::sql_types::Point`]: ::diesel_geometry::sql_types::Point //! [`ToSql`]: ::diesel::serialize::ToSql //! [`FromSql`]: ::diesel::deserialize::FromSql //! //! ## Getting help //! //! If you run into problems, email the developers. //! You can come ask for help at //! [diesel_geometry devs mailing list](mailto:diesel_geometry-devel@thinkalexandria.com) extern crate byteorder; #[cfg(test)] #[macro_use] extern crate cfg_if; #[macro_use] extern crate diesel; pub mod data_types; pub mod expression; #[cfg(feature = "postgres")] pub mod pg; pub mod sql_types; #[cfg(test)] pub mod test_helpers; //pub mod expression; pub mod expression_methods; pub mod prelude { //! Re-exports important traits and types. Meant to be glob imported when using Diesel //! Geometry. pub use expression_methods::*; } pub mod dsl { //! Includes various helper types and bare functions which are named too //! generically to be included in prelude, but are often used when using Diesel Geometry. #[doc(inline)] pub use expression::dsl::*; }