Repository: diesel-rs/diesel
File: diesel/src/pg/expression/functions.rs (Rust)

Code before:
    /// # }
    /// ```
    fn array_upper<Arr: ArrayOrNullableArray + SingleValue>(array: Arr, dimension: Integer) -> Nullable<Integer>;
}

#[cfg(feature = "postgres_backend")]
define_sql_function! {
    /// Randomly shuffles the first dimension of the array.
    ///
    /// # Example
    ///
    /// ```rust
    /// # include!("../../doctest_setup.rs");
    /// #
    /// # fn main() {
    /// #     run_test().unwrap();
    /// # }
    /// #
    /// # fn run_test() -> QueryResult<()> {
    /// #     use diesel::dsl::array_shuffle;
    /// #     use diesel::sql_types::{Array, Integer};
    /// #     let connection = &mut establish_connection();
    /// let shuffled = diesel::select(array_shuffle::<Array<Integer>, _>(vec![1, 2, 3, 4, 5]))
    ///     .get_result::<Vec<i32>>(connection)?;
    /// assert_eq!(5, shuffled.len());
    /// assert!(shuffled != vec![1, 2, 3, 4, 5]);  // It's very unlikely to get the same order
    /// #     Ok(())
    /// # }
    /// ```
    fn array_shuffle<Arr: ArrayOrNullableArray + SingleValue>(array: Arr) -> Arr;
}


Review comment (bug):
Obviously this test will fail in just under 1% of runs, when the shuffle happens to do nothing. I'm a bit uncomfortable about this - one test like this might be fine, but if we set a precedent and we had many tests like this our suite will become flaky and "just rerun the suite" will become a common approach rather than digging into the problem.
@weiznich please let me know if you think I'm being overcautious.
A simple alternative would be
```rust
  println!("{:?}", shuffled); // e.g., `[3, 2, 5, 1, 4]`
```


Code after:
    /// #     Ok(())
    /// # }
    /// ```
    fn array_upper<Arr: ArrayOrNullableArray + SingleValue>(array: Arr, dimension: Integer) -> Nullable<Integer>;
}

#[cfg(feature = "postgres_backend")]
define_sql_function! {
    /// Randomly shuffles the first dimension of the array.
    ///
    /// # Example
    ///
    // This function requires postgres >= 16.0
    // which we cannot expect to be widly used at the
    // point of writing this comment, so we skip running this test
    /// ```rust,no_run
    /// # include!("../../doctest_setup.rs");
    /// #
    /// # fn main() {
    /// #     run_test().unwrap();
    /// # }
    /// #
    /// # fn run_test() -> QueryResult<()> {
    /// #     use diesel::dsl::array_shuffle;
    /// #     use diesel::sql_types::{Array, Integer};
    /// #     let connection = &mut establish_connection();
    /// let shuffled = diesel::select(array_shuffle::<Array<Integer>, _>(vec![1, 2, 3, 4, 5]))
    ///     .get_result::<Vec<i32>>(connection)?;
    /// assert_eq!(5, shuffled.len());
    /// assert_eq!(shuffled.iter().sum::<i32>(), 15);
    /// #     Ok(())
    /// # }
    /// ```
    fn array_shuffle<Arr: ArrayOrNullableArray + SingleValue>(array: Arr) -> Arr;
}

#[cfg(feature = "postgres_backend")]
define_sql_function! {
    /// Converts any SQL value to json
    ///
    /// # Example
    ///
    /// ```rust
    /// # include!("../../doctest_setup.rs");
    /// #
    /// # fn main() {
    /// #     #[cfg(feature = "serde_json")]
    /// #     run_test().unwrap();
    /// # }
    /// #
    /// # #[cfg(feature = "serde_json")]