Use `_start` and `_end` suffixes on string functions

4 files changed, 153 insertions, 37 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb04001..f59a135 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,10 @@
 ## Unreleased
 
 - The `bit_array` module gains the `bit_size` and `starts_with` functions.
+- Ths `string` module gains the `drop_start`, `drop_end`, `pad_start`,
+  `pad_end`, `trim_start`, and `trim_end` functions. These replace the
+  `drop_left`, `drop_right`, `pad_left`, `pad_right`, `trim_left`, and
+  `trim_right` functions, which have been deprecated.
 
 ## v0.41.0 - 2024-10-31
 
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index 8a3a57e..ddfc89f 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -247,7 +247,21 @@ pub fn crop(from string: String, before substring: String) -> String
 /// // -> "e Lone Gunmen"
 /// ```
 ///
+@deprecated("Use `string.drop_start` instead.")
 pub fn drop_left(from string: String, up_to num_graphemes: Int) -> String {
+  drop_start(string, num_graphemes)
+}
+
+/// Drops *n* graphemes from the start of a `String`.
+///
+/// ## Examples
+///
+/// ```gleam
+/// drop_start(from: "The Lone Gunmen", up_to: 2)
+/// // -> "e Lone Gunmen"
+/// ```
+///
+pub fn drop_start(from string: String, up_to num_graphemes: Int) -> String {
   case num_graphemes < 0 {
     True -> string
     False -> slice(string, num_graphemes, length(string) - num_graphemes)
@@ -263,7 +277,21 @@ pub fn drop_left(from string: String, up_to num_graphemes: Int) -> String {
 /// // -> "Cigarette Smoking M"
 /// ```
 ///
+@deprecated("Use `string.drop_end` instead.")
 pub fn drop_right(from string: String, up_to num_graphemes: Int) -> String {
+  drop_end(string, num_graphemes)
+}
+
+/// Drops *n* graphemes from the end of a `String`.
+///
+/// ## Examples
+///
+/// ```gleam
+/// drop_end(from: "Cigarette Smoking Man", up_to: 2)
+/// // -> "Cigarette Smoking M"
+/// ```
+///
+pub fn drop_end(from string: String, up_to num_graphemes: Int) -> String {
   case num_graphemes < 0 {
     True -> string
     False -> slice(string, 0, length(string) - num_graphemes)
@@ -486,11 +514,39 @@ fn do_join(strings: List(String), separator: String) -> String {
 /// // -> "121"
 /// ```
 ///
+@deprecated("Use `string.pad_start` instead.")
 pub fn pad_left(
   string: String,
   to desired_length: Int,
   with pad_string: String,
 ) -> String {
+  pad_start(string, desired_length, pad_string)
+}
+
+/// Pads the start of a `String` until it has a given length.
+///
+/// ## Examples
+///
+/// ```gleam
+/// pad_start("121", to: 5, with: ".")
+/// // -> "..121"
+/// ```
+///
+/// ```gleam
+/// pad_start("121", to: 3, with: ".")
+/// // -> "121"
+/// ```
+///
+/// ```gleam
+/// pad_start("121", to: 2, with: ".")
+/// // -> "121"
+/// ```
+///
+pub fn pad_start(
+  string: String,
+  to desired_length: Int,
+  with pad_string: String,
+) -> String {
   let current_length = length(string)
   let to_pad_length = desired_length - current_length
 
@@ -519,11 +575,39 @@ pub fn pad_left(
 /// // -> "123"
 /// ```
 ///
+@deprecated("Use `string.pad_end` instead.")
 pub fn pad_right(
   string: String,
   to desired_length: Int,
   with pad_string: String,
 ) -> String {
+  pad_end(string, desired_length, pad_string)
+}
+
+/// Pads the end of a `String` until it has a given length.
+///
+/// ## Examples
+///
+/// ```gleam
+/// pad_end("123", to: 5, with: ".")
+/// // -> "123.."
+/// ```
+///
+/// ```gleam
+/// pad_end("123", to: 3, with: ".")
+/// // -> "123"
+/// ```
+///
+/// ```gleam
+/// pad_end("123", to: 2, with: ".")
+/// // -> "123"
+/// ```
+///
+pub fn pad_end(
+  string: String,
+  to desired_length: Int,
+  with pad_string: String,
+) -> String {
   let current_length = length(string)
   let to_pad_length = desired_length - current_length
 
@@ -582,12 +666,26 @@ type Direction {
 /// // -> "hats  \n"
 /// ```
 ///
+@deprecated("Use `string.trim_start` instead")
 pub fn trim_left(string: String) -> String {
-  do_trim_left(string)
+  trim_start(string)
+}
+
+/// Removes whitespace at the start of a `String`.
+///
+/// ## Examples
+///
+/// ```gleam
+/// trim_start("  hats  \n")
+/// // -> "hats  \n"
+/// ```
+///
+pub fn trim_start(string: String) -> String {
+  do_trim_start(string)
 }
 
-@external(javascript, "../gleam_stdlib.mjs", "trim_left")
-fn do_trim_left(string: String) -> String {
+@external(javascript, "../gleam_stdlib.mjs", "trim_start")
+fn do_trim_start(string: String) -> String {
   erl_trim(string, Leading)
 }
 
@@ -600,12 +698,26 @@ fn do_trim_left(string: String) -> String {
 /// // -> "  hats"
 /// ```
 ///
+@deprecated("Use `string.trim_end` instead")
 pub fn trim_right(string: String) -> String {
-  do_trim_right(string)
+  trim_end(string)
+}
+
+/// Removes whitespace at the end of a `String`.
+///
+/// ## Examples
+///
+/// ```gleam
+/// trim_end("  hats  \n")
+/// // -> "  hats"
+/// ```
+///
+pub fn trim_end(string: String) -> String {
+  do_trim_end(string)
 }
 
-@external(javascript, "../gleam_stdlib.mjs", "trim_right")
-fn do_trim_right(string: String) -> String {
+@external(javascript, "../gleam_stdlib.mjs", "trim_end")
+fn do_trim_end(string: String) -> String {
   erl_trim(string, Trailing)
 }
 
diff --git a/src/gleam_stdlib.mjs b/src/gleam_stdlib.mjs
index 4d198cb..a70309e 100644
--- a/src/gleam_stdlib.mjs
+++ b/src/gleam_stdlib.mjs
@@ -299,14 +299,14 @@ const left_trim_regex = new RegExp(`^([${unicode_whitespaces}]*)`, "g");
 const right_trim_regex = new RegExp(`([${unicode_whitespaces}]*)$`, "g");
 
 export function trim(string) {
-  return trim_left(trim_right(string));
+  return trim_start(trim_end(string));
 }
 
-export function trim_left(string) {
+export function trim_start(string) {
   return string.replace(left_trim_regex, "");
 }
 
-export function trim_right(string) {
+export function trim_end(string) {
   return string.replace(right_trim_regex, "");
 }
 
diff --git a/test/gleam/string_test.gleam b/test/gleam/string_test.gleam
index 4d03fee..c49f543 100644
--- a/test/gleam/string_test.gleam
+++ b/test/gleam/string_test.gleam
@@ -164,15 +164,15 @@ pub fn trim_test() {
   |> should.equal("hats")
 }
 
-pub fn trim_left_test() {
+pub fn trim_start_test() {
   "  hats  \n"
-  |> string.trim_left
+  |> string.trim_start
   |> should.equal("hats  \n")
 }
 
-pub fn trim_right_test() {
+pub fn trim_end_test() {
   "  hats  \n"
-  |> string.trim_right
+  |> string.trim_end
   |> should.equal("  hats")
 }
 
@@ -451,90 +451,90 @@ pub fn crop_test() {
   |> should.equal("gleam")
 }
 
-pub fn drop_left_test() {
+pub fn drop_start_test() {
   "gleam"
-  |> string.drop_left(up_to: 2)
+  |> string.drop_start(up_to: 2)
   |> should.equal("eam")
 
   "gleam"
-  |> string.drop_left(up_to: 6)
+  |> string.drop_start(up_to: 6)
   |> should.equal("")
 
   "gleam"
-  |> string.drop_left(up_to: -2)
+  |> string.drop_start(up_to: -2)
   |> should.equal("gleam")
 }
 
-pub fn drop_left_3499_test() {
+pub fn drop_start_3499_test() {
   // https://github.com/gleam-lang/gleam/issues/3499
   "\r]"
-  |> string.drop_left(1)
+  |> string.drop_start(1)
   |> should.equal("]")
 }
 
-pub fn drop_right_test() {
+pub fn drop_end_test() {
   "gleam"
-  |> string.drop_right(up_to: 2)
+  |> string.drop_end(up_to: 2)
   |> should.equal("gle")
 
   "gleam"
-  |> string.drop_right(up_to: 5)
+  |> string.drop_end(up_to: 5)
   |> should.equal("")
 
   "gleam"
-  |> string.drop_right(up_to: -2)
+  |> string.drop_end(up_to: -2)
   |> should.equal("gleam")
 }
 
-pub fn pad_left_test() {
+pub fn pad_start_test() {
   "121"
-  |> string.pad_left(to: 5, with: ".")
+  |> string.pad_start(to: 5, with: ".")
   |> should.equal("..121")
 
   "121"
-  |> string.pad_left(to: 3, with: ".")
+  |> string.pad_start(to: 3, with: ".")
   |> should.equal("121")
 
   "121"
-  |> string.pad_left(to: 2, with: ".")
+  |> string.pad_start(to: 2, with: ".")
   |> should.equal("121")
 
   "121"
-  |> string.pad_left(to: 4, with: "XY")
+  |> string.pad_start(to: 4, with: "XY")
   |> should.equal("X121")
 
   "121"
-  |> string.pad_left(to: 5, with: "XY")
+  |> string.pad_start(to: 5, with: "XY")
   |> should.equal("XY121")
 
   "121"
-  |> string.pad_left(to: 6, with: "XY")
+  |> string.pad_start(to: 6, with: "XY")
   |> should.equal("XYX121")
 }
 
-pub fn pad_right_test() {
+pub fn pad_end_test() {
   "121"
-  |> string.pad_right(to: 5, with: ".")
+  |> string.pad_end(to: 5, with: ".")
   |> should.equal("121..")
 
   "121"
-  |> string.pad_right(to: 3, with: ".")
+  |> string.pad_end(to: 3, with: ".")
   |> should.equal("121")
 
   "121"
-  |> string.pad_right(to: 2, with: ".")
+  |> string.pad_end(to: 2, with: ".")
   |> should.equal("121")
 
   "121"
-  |> string.pad_right(to: 4, with: "XY")
+  |> string.pad_end(to: 4, with: "XY")
   |> should.equal("121X")
 
   "121"
-  |> string.pad_right(to: 5, with: "XY")
+  |> string.pad_end(to: 5, with: "XY")
   |> should.equal("121XY")
 
   "121"
-  |> string.pad_right(to: 6, with: "XY")
+  |> string.pad_end(to: 6, with: "XY")
   |> should.equal("121XYX")
 }