Rename slow functions to include a copy_ prefix

src/glearray.gleam

@@ -47,6 +47,8 @@ pub fn to_list(array: Array(a)) -> List(a)
 
 /// Returns the number of elements in the array.
 ///
+/// ## Performance
+///
 /// This function is very efficient and runs in constant time.
 ///
 /// ## Examples
@@ -70,6 +72,8 @@ pub fn length(of array: Array(a)) -> Int
 /// `Error(Nil)` is returned if `index` is less than 0 or greater than
 /// or equal to `length(array)`.
 ///
+/// ## Performance
+///
 /// This function is very efficient and runs in constant time.
 ///
 /// ## Examples
@@ -101,19 +105,24 @@ fn do_get(array: Array(a), index: Int) -> a
 /// not valid.
 /// See also [`insert`](#insert) and [`push`](#push).
 ///
+/// ## Performance
+///
+/// This function has to copy the entire array, making it very inefficient
+/// especially for larger arrays.
+///
 /// ## Examples
 ///
 /// ```gleam
-/// > from_list(["a", "b", "c"]) |> set(1, "x")
+/// > from_list(["a", "b", "c"]) |> copy_set(1, "x")
 /// Ok(from_list(["a", "x", "c"]))
 /// ```
 ///
 /// ```gleam
-/// > from_list(["a", "b", "c"]) |> set(3, "x")
+/// > from_list(["a", "b", "c"]) |> copy_set(3, "x")
 /// Error(Nil)
 /// ```
 ///
-pub fn set(
+pub fn copy_set(
   in array: Array(a),
   at index: Int,
   value value: a,
@@ -134,16 +143,21 @@ fn is_valid_index(array: Array(a), index: Int) -> Bool {
 
 /// Adds a single element to the back of the given array.
 ///
+/// ## Performance
+///
+/// This function has to copy the entire array, making it very inefficient
+/// especially for larger arrays.
+///
 /// ## Examples
 ///
 /// ```gleam
-/// > new() |> push(1) |> push(2) |> to_list
+/// > new() |> copy_push(1) |> copy_push(2) |> to_list
 /// [1, 2]
 /// ```
 ///
 @external(erlang, "erlang", "append_element")
 @external(javascript, "./glearray_ffi.mjs", "push")
-pub fn push(onto array: Array(a), value value: a) -> Array(a)
+pub fn copy_push(onto array: Array(a), value value: a) -> Array(a)
 
 /// Inserts an element into the array at the given index.
 ///
@@ -155,29 +169,34 @@ pub fn push(onto array: Array(a), value value: a) -> Array(a)
 /// If the index is equal to `length(array)`, this function behaves like
 /// [`push`](#push).
 ///
+/// ## Performance
+///
+/// This function has to copy the entire array, making it very inefficient
+/// especially for larger arrays.
+///
 /// ## Examples
 ///
 /// ```gleam
-/// > from_list(["a", "b"]) |> insert(0, "c")
+/// > from_list(["a", "b"]) |> copy_insert(0, "c")
 /// Ok(from_list(["c", "a", "b"]))
 /// ```
 ///
 /// ```gleam
-/// > from_list(["a", "b"]) |> insert(1, "c")
+/// > from_list(["a", "b"]) |> copy_insert(1, "c")
 /// Ok(from_list(["a", "c", "b"]))
 /// ```
 ///
 /// ```gleam
-/// > from_list(["a", "b"]) |> insert(2, "c")
+/// > from_list(["a", "b"]) |> copy_insert(2, "c")
 /// Ok(from_list(["a", "b", "c"]))
 /// ```
 ///
 /// ```gleam
-/// > from_list(["a", "b"]) |> insert(3, "c")
+/// > from_list(["a", "b"]) |> copy_insert(3, "c")
 /// Error(Nil)
 /// ```
 ///
-pub fn insert(
+pub fn copy_insert(
   into array: Array(a),
   at index: Int,
   value value: a,

test/glearray_test.gleam

@@ -53,50 +53,50 @@ pub fn get_test() {
 
 pub fn set_test() {
   let array = glearray.from_list([1, 2, 3, 4])
-  let assert Ok(modified) = glearray.set(in: array, at: 1, value: 10)
+  let assert Ok(modified) = glearray.copy_set(in: array, at: 1, value: 10)
   array
   |> glearray.to_list
   |> should.equal([1, 2, 3, 4])
   modified
   |> glearray.to_list
   |> should.equal([1, 10, 3, 4])
 
-  glearray.set(array, -1, 0)
+  glearray.copy_set(array, -1, 0)
   |> should.be_error
-  glearray.set(array, glearray.length(array), 0)
+  glearray.copy_set(array, glearray.length(array), 0)
   |> should.be_error
-  glearray.set(glearray.new(), 0, 0)
+  glearray.copy_set(glearray.new(), 0, 0)
   |> should.be_error
 }
 
 pub fn push_test() {
   glearray.new()
-  |> glearray.push(1)
-  |> glearray.push(2)
-  |> glearray.push(3)
-  |> glearray.push(4)
+  |> glearray.copy_push(1)
+  |> glearray.copy_push(2)
+  |> glearray.copy_push(3)
+  |> glearray.copy_push(4)
   |> glearray.to_list
   |> should.equal([1, 2, 3, 4])
 
   // Ensure immutability; relevant for the JS impl
   glearray.from_list([1, 2, 3])
-  |> function.tap(glearray.push(_, 4))
+  |> function.tap(glearray.copy_push(_, 4))
   |> glearray.to_list
   |> should.equal([1, 2, 3])
 }
 
 pub fn insert_test() {
   let array = glearray.from_list([1, 2, 3])
   array
-  |> glearray.insert(at: 0, value: 9)
+  |> glearray.copy_insert(at: 0, value: 9)
   |> result.map(glearray.to_list)
   |> should.equal(Ok([9, 1, 2, 3]))
   array
-  |> glearray.insert(at: 2, value: -1)
+  |> glearray.copy_insert(at: 2, value: -1)
   |> result.map(glearray.to_list)
   |> should.equal(Ok([1, 2, -1, 3]))
   array
-  |> glearray.insert(3, 20)
+  |> glearray.copy_insert(3, 20)
   |> result.map(glearray.to_list)
   |> should.equal(Ok([1, 2, 3, 20]))
 }