Enum ActiveValue 

pub enum ActiveValue<V>
where
    V: Into<Value>,
{
    Set(V),
    Unchanged(V),
    NotSet,
}

The state of a field in an ActiveModel.

There are three possible states represented by three enum variants:

• Set - a value that’s explicitly set by the application and sent to the database.
• Unchanged - an existing, unchanged value from the database.
• NotSet - an undefined value (nothing is sent to the database).

The difference between these states is useful when constructing INSERT and UPDATE SQL statements (see an example below). It’s also useful for knowing which fields have changed in a record.

Examples

use sea_orm::tests_cfg::{cake, fruit};
use sea_orm::{DbBackend, entity::*, query::*};

// Here, we use `NotSet` to let the database automatically generate an `id`.
// This is different from `Set(None)` that explicitly sets `cake_id` to `NULL`.
assert_eq!(
    Insert::one(fruit::ActiveModel {
        id: ActiveValue::NotSet,
        name: ActiveValue::Set("Orange".to_owned()),
        cake_id: ActiveValue::Set(None),
    })
    .build(DbBackend::Postgres)
    .to_string(),
    r#"INSERT INTO "fruit" ("name", "cake_id") VALUES ('Orange', NULL)"#
);

// Here, we update the record, set `cake_id` to the new value
// and use `NotSet` to avoid updating the `name` field.
// `id` is the primary key, so it's used in the condition and not updated.
assert_eq!(
    Update::one(fruit::ActiveModel {
        id: ActiveValue::Unchanged(1),
        name: ActiveValue::NotSet,
        cake_id: ActiveValue::Set(Some(2)),
    })
    .validate()
    .unwrap()
    .build(DbBackend::Postgres)
    .to_string(),
    r#"UPDATE "fruit" SET "cake_id" = 2 WHERE "fruit"."id" = 1"#
);

Variants

Set(V)

A Value that’s explicitly set by the application and sent to the database.

Use this to insert or set a specific value.

When editing an existing value, you can use set_ne to preserve the Unchanged state when the new value is the same as the old one. Then you can meaningfully use methods like crate::ActiveModelTrait::is_changed.

Unchanged(V)

An existing, unchanged Value from the database.

You get these when you query an existing Model from the database and convert it into an ActiveModel.

When you edit it, you can use set_ne to preserve this “unchanged” state if the new value is the same as the old one. Then you can meaningfully use methods like crate::ActiveModelTrait::is_changed.

NotSet

An undefined Value. Nothing is sent to the database.

When you create a new ActiveModel, its fields are NotSet by default.

This can be useful when:

• You insert a new record and want the database to generate a default value (e.g., an id).
• In an UPDATE statement, you don’t want to update some field.

Implementations

impl<V> ActiveValue<V>

where V: Into<Value>,

pub fn set(value: V) -> Self

Create an ActiveValue::Set

pub fn is_set(&self) -> bool

Check if the ActiveValue is ActiveValue::Set

pub fn is_set_and(&self, f: impl FnOnce(&V) -> bool) -> bool

Check if the ActiveValue is ActiveValue::Set and that the inner value matches a given predicate.

pub fn unchanged(value: V) -> Self

Create an ActiveValue::Unchanged

pub fn is_unchanged(&self) -> bool

Check if the ActiveValue is ActiveValue::Unchanged

pub fn is_unchanged_and(&self, f: impl FnOnce(&V) -> bool) -> bool

Check if the ActiveValue is ActiveValue::Unchanged and that the inner value matches a given predicate.

pub fn not_set() -> Self

Create an ActiveValue::NotSet

pub fn is_not_set(&self) -> bool

Check if the ActiveValue is ActiveValue::NotSet

pub fn take(&mut self) -> Option<V>

Take ownership of the inner value, also setting self to NotSet

pub fn unwrap(self) -> V

Get an owned value of the ActiveValue

Panics

Panics if it is ActiveValue::NotSet

pub fn into_value(self) -> Option<Value>

Take ownership of the inner value, consuming self

pub fn into_wrapped_value(self) -> ActiveValue<Value>

Wrap the Value into a ActiveValue<Value>

pub fn reset(&mut self)

Reset the value from ActiveValue::Unchanged to ActiveValue::Set, leaving ActiveValue::NotSet untouched.

pub fn set_ne(&mut self, value: V)

where V: PartialEq,

Set(value), except when self.is_unchanged() and value equals the current Unchanged value.

This is useful when you have an Unchanged value from the database, then update it using this method, and then use .is_unchanged() to see whether it has actually changed.

The same nice effect applies to the entire ActiveModel. You can now meaningfully use crate::ActiveModelTrait::is_changed to see whether are any changes that need to be saved to the database.

Examples

let mut value = ActiveValue::Unchanged("old");

// This wouldn't be the case if we used plain `value = Set("old");`
value.set_ne("old");
assert!(value.is_unchanged());

// Only when we change the actual `&str` value, it becomes `Set`
value.set_ne("new");
assert_eq!(value.is_unchanged(), false);
assert_eq!(value, ActiveValue::Set("new"));

pub fn set_if_not_equals(&mut self, value: V)

where V: PartialEq,

Alias for ActiveValue::set_ne. Kept for compatibility.

pub fn set_ne_and(&mut self, value: V, f: impl FnOnce(&V) -> bool)

where V: PartialEq,

Set(value), except when self.is_unchanged(), value equals the current Unchanged value, and value does not match a given predicate.

This is useful in the same situations as ActiveValue::set_ne as well as when you want to leave an existing Set value alone depending on a condition, such as ensuring a None value never replaced an existing Some value. This can come up when trying to merge two ActiveValues.

Examples

let mut value = ActiveValue::Set(Some("old"));

// since Option::is_some(None) == false, we leave the existing set value alone
value.set_ne_and(None, Option::is_some);
assert_eq!(value, ActiveValue::Set(Some("old")));

// since Option::is_some(Some("new")) == true, we replace the set value
value.set_ne_and(Some("new"), Option::is_some);
assert_eq!(value, ActiveValue::Set(Some("new")));

pub fn set_if_not_equals_and(&mut self, value: V, f: impl FnOnce(&V) -> bool)

where V: PartialEq,

Alias for ActiveValue::set_ne_and. Kept for compatibility.

pub fn set_if_unset(&mut self, value: V)

Set(value) if self.is_not_set(), no-op otherwise. Similar to “null coalescing” or Option, but without returning the inner value if it is set/unchanged.

Examples

let mut set_value = ActiveValue::Set(true);
let mut unchanged_value = ActiveValue::Unchanged(true);
let mut notset_value = ActiveValue::NotSet;

// since `set_value.is_not_set == false`, we leave the existing set value alone
set_value.set_if_unset(false);
assert_eq!(set_value, ActiveValue::Set(true));

// since `set_value.is_not_set == false`, we leave the existing set value alone
unchanged_value.set_if_unset(false);
assert_eq!(unchanged_value, ActiveValue::Unchanged(true));

// since `set_value.is_not_set == true`, we fill with the provided value
notset_value.set_if_unset(false);
assert_eq!(notset_value, ActiveValue::Set(false));

pub fn set_if_unset_with(&mut self, f: impl FnOnce() -> V)

Set(f()) if self.is_not_set(), no-op otherwise. Similar to “null coalescing” or Option, but without returning the inner value if it is set/unchanged.

This can be useful if the value you want to replace it with is expensive to compute, or has side-effects which need to be ran (like logging).

Examples

let mut set_value = ActiveValue::Set(true);
let mut unchanged_value = ActiveValue::Unchanged(true);
let mut notset_value = ActiveValue::NotSet;

let mut count = 0;
// since `set_value.is_not_set == false`, we leave the existing set value alone
set_value.set_if_unset_with(|| {
    count += 1;
    false
});
assert_eq!(set_value, ActiveValue::Set(true));

// since `set_value.is_not_set == false`, we leave the existing set value alone
unchanged_value.set_if_unset_with(|| {
    count += 1;
    false
});
assert_eq!(unchanged_value, ActiveValue::Unchanged(true));

// since `set_value.is_not_set == true`, we fill with the result of the provided computation.
notset_value.set_if_unset_with(|| {
    count += 1;
    false
});
assert_eq!(notset_value, ActiveValue::Set(false));

// Only the last closure actually executed.
assert_eq!(count, 1);

pub fn set_if_unset_default(&mut self)

where V: Default,

Set(V::default()) if self.is_not_set(), no-op otherwise. Similar to “null coalescing” or Option, but without returning the inner value if it is set/unchanged.

Convenient shorthand for set_if_unset(Default::default()).

Examples

let mut set_value = ActiveValue::Set(100);
let mut unchanged_value = ActiveValue::Unchanged(100);
let mut notset_value = ActiveValue::NotSet;

// since `set_value.is_not_set == false`, we leave the existing set value alone
set_value.set_if_unset_default();
assert_eq!(set_value, ActiveValue::Set(100));

// since `set_value.is_not_set == false`, we leave the existing set value alone
unchanged_value.set_if_unset_default();
assert_eq!(unchanged_value, ActiveValue::Unchanged(100));

// since `set_value.is_not_set == true`, we fill with the default int (0)
notset_value.set_if_unset_default();
assert_eq!(notset_value, ActiveValue::Set(0));

pub fn try_as_ref(&self) -> Option<&V>

Get the inner value, unless self is NotSet.

There’s also a panicking version: ActiveValue::as_ref.

Examples

assert_eq!(ActiveValue::Unchanged(42).try_as_ref(), Some(&42));
assert_eq!(ActiveValue::Set(42).try_as_ref(), Some(&42));
assert_eq!(ActiveValue::NotSet.try_as_ref(), None::<&i32>);

impl<V> ActiveValue<Option<V>>

where V: Into<Value> + Nullable,

pub fn as_option(&self) -> Option<&V>

Flatten an &ActiveValue<Option<V>> into an Option<&V>, folding NotSet together with the inner None, and Set / Unchanged together with the inner Some.

Shorthand for self.try_as_ref().and_then(Option::as_ref). For the owned version, see ActiveValue::into_option.

use sea_orm::ActiveValue;

let x: ActiveValue<Option<i32>> = ActiveValue::Set(Some(1));
let y: ActiveValue<Option<i32>> = ActiveValue::Set(None);
let z: ActiveValue<Option<i32>> = ActiveValue::NotSet;

assert_eq!(x.as_option(), Some(&1));
assert_eq!(y.as_option(), None);
assert_eq!(z.as_option(), None);

// composes cleanly with a predicate, on a single line
assert!(x.as_option().is_some_and(|v| *v == 1));

pub fn into_option(self) -> Option<V>

Flatten an ActiveValue<Option<V>> into an Option<V>, folding NotSet together with the inner None, and Set / Unchanged together with the inner Some.

For a borrowing version, see ActiveValue::as_option.

use sea_orm::ActiveValue;

let x: ActiveValue<Option<i32>> = ActiveValue::Set(Some(1));
let y: ActiveValue<Option<i32>> = ActiveValue::Set(None);
let z: ActiveValue<Option<i32>> = ActiveValue::NotSet;

assert_eq!(x.into_option(), Some(1));
assert_eq!(y.into_option(), None);
assert_eq!(z.into_option(), None);

Trait Implementations

impl<V> AsRef<V> for ActiveValue<V>

where V: Into<Value>,

fn as_ref(&self) -> &V

Panics

Panics if it is ActiveValue::NotSet.

See ActiveValue::try_as_ref for a fallible non-panicking version.

impl<V> Clone for ActiveValue<V>

where V: Into<Value> + Clone,

fn clone(&self) -> ActiveValue<V>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<V> Debug for ActiveValue<V>

where V: Into<Value> + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<V> Default for ActiveValue<V>

where V: Into<Value>,

fn default() -> Self

Create an ActiveValue::NotSet

impl<V> DefaultActiveValue for ActiveValue<V>

where V: Into<Value> + ValueType + Nullable,

fn default_value(&self) -> Self

Default::default() if implemented, dummy value otherwise.

impl<V> DefaultActiveValueNone for ActiveValue<Option<V>>

where V: Into<Value> + Nullable,

fn default_value(&self) -> Self

Always None.

impl<V> DefaultActiveValueNotSet for &ActiveValue<V>

where V: Into<Value>,

type Value = ActiveValue<V>

The owned value type.

fn default_value(&self) -> Self::Value

Always NotSet.

impl<V> From<ActiveValue<V>> for ActiveValue<Option<V>>

where V: Into<Value> + Nullable,

fn from(value: ActiveValue<V>) -> Self

Converts to this type from the input type.

impl<V> PartialEq for ActiveValue<V>

where V: Into<Value> + PartialEq,

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.