Repository: diesel-rs/diesel
File: diesel/src/expression_methods/global_expression_methods.rs (Rust)

Code before:
    /// # include!("../doctest_setup.rs");
    /// # use diesel::sql_types::*;
    /// # use schema::users;
    /// #
    /// table! {
    ///     posts {
    ///         id -> Integer,
    ///         user_id -> Integer,
    ///         author_name -> Nullable<VarChar>,
    ///     }
    /// }
    /// #
    /// # joinable!(posts -> users (user_id));
    /// # allow_tables_to_appear_in_same_query!(posts, users);
    ///
    /// fn main() {
    ///     use self::posts;
    ///     use self::users;
    ///     let connection = &mut establish_connection();
    ///
    ///     let data = posts::table.left_join(users::table)
    ///         .select((users::id, posts::author_name.assume_not_null()).nullable())
    ///         .load::<Option<(i32, String)>>(connection);
    ///     // This will cause the `Option` to be `None` where the `left_join` succeeded but the
    ///     // `author_name` turned out to be `NULL`, because `Option` deserialization relies
    ///     // on encountering an unexpected `NULL` while deserializing the inner fields.
    ///     println!("{:?}", data);
    /// }
    /// ```
    fn assume_not_null(self) -> dsl::AssumeNotNull<Self> {
        assume_not_null::AssumeNotNull::new(self)
    }
}

impl<T> ExpressionMethods for T
where
    T: Expression,
    T::SqlType: SingleValue,
{
}

/// Methods present on all expressions
pub trait NullableExpressionMethods: Expression + Sized {
    /// Converts this potentially non-null expression into one which is treated
    /// as nullable. This method has no impact on the generated SQL, and is only
    /// used to allow certain comparisons that would otherwise fail to compile.
    ///
    /// # Example
    /// ```no_run
    /// # #![allow(dead_code)]
    /// # include!("../doctest_setup.rs");

Review comment (suggestion):
I believe this documentation belongs to the `FromSqlRow` impl of `Option<T>` instead, as this can also happen in other constructed cases. I would rather include an example that really returns an error from `load()`

Code after:
    /// # use diesel::sql_types::*;
    /// #
    /// table! {
    ///     animals {
    ///         id -> Integer,
    ///         species -> VarChar,
    ///         legs -> Integer,
    ///         name -> Nullable<VarChar>,
    ///     }
    /// }
    ///
    /// fn main() {
    ///     use diesel::result::{Error, UnexpectedNullError};
    ///     use self::animals::dsl::*;
    ///     let connection = &mut establish_connection();
    ///
    ///     let result = animals
    ///         .select(name.assume_not_null())
    ///         .load::<String>(connection);
    ///     assert!(matches!(
    ///         result,
    ///         Err(Error::DeserializationError(err)) if err.is::<UnexpectedNullError>()
    ///     ));
    /// }
    /// ```
    ///
    /// ## Advanced usage - use only if you're sure you know what you're doing!
    ///
    /// This will cause the `Option` to be `None` where the `left_join` succeeded but the
    /// `author_name` turned out to be `NULL`, due to how `Option` deserialization works.
    /// (see [`Queryable` documentation](crate::deserialize::Queryable))
    ///
    /// ```rust
    /// # #![allow(dead_code)]
    /// # include!("../doctest_setup.rs");
    /// # use diesel::sql_types::*;
    /// # use schema::users;
    /// #
    /// table! {
    ///     posts {
    ///         id -> Integer,
    ///         user_id -> Integer,
    ///         author_name -> Nullable<Text>,
    ///     }
    /// }
    /// #
    /// # joinable!(posts -> users (user_id));
    /// # allow_tables_to_appear_in_same_query!(posts, users);
    ///
    /// fn main() {
    ///     use self::posts;