From 051d8f75350e54009180cc2fa5e5f86c92db1e13 Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Tue, 22 Dec 2020 06:59:25 +0100
Subject: [PATCH] Make string-pad take an optional START parameter

* lisp/emacs-lisp/subr-x.el (string-pad): Alter the calling
convention.
---
 doc/lispref/strings.texi             |  8 ++++----
 lisp/emacs-lisp/shortdoc.el          |  2 +-
 lisp/emacs-lisp/subr-x.el            | 14 ++++++++------
 test/lisp/emacs-lisp/subr-x-tests.el |  2 +-
 4 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 80e936e9743..ef848ac5107 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -418,13 +418,13 @@ Split @var{string} into a list of strings on newline boundaries.  If
 @var{omit-nulls}, remove empty lines from the results.
 @end defun
 
-@defun string-pad string length &optional padding
+@defun string-pad string length &optional padding start
 Pad @var{string} to the be of @var{length} using @var{padding} as the
 padding character (defaulting to the space character).  If
 @var{string} is shorter than @var{length}, no padding is done.  If
-@var{length} is positive, the padding is done to the end of the
-string, and if it's negative, to the start of the string (using the
-absolute value).
+@var{start} is @code{nil} (or not present), the padding is done to the
+end of the string, and if it's non-@code{nil}, to the start of the
+string.
 @end defun
 
 @defun string-chop-newline string
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index eb57e706608..e9e1be1d550 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -134,7 +134,7 @@ There can be any number of :example/:result elements."
   (string-pad
    :eval (string-pad "foo" 5)
    :eval (string-pad "foobar" 5)
-   :eval (string-pad "foo" -5 ?-))
+   :eval (string-pad "foo" 5 ?- t))
   (mapcar
    :eval (mapcar #'identity "123"))
   (format
diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
index b79482fd4b3..dc046c3d76a 100644
--- a/lisp/emacs-lisp/subr-x.el
+++ b/lisp/emacs-lisp/subr-x.el
@@ -322,7 +322,7 @@ The boundaries that match REGEXP are included in the result."
       (push (substring string start-substring) result)
       (nreverse result))))
 
-(defun string-pad (string length &optional padding)
+(defun string-pad (string length &optional padding start)
   "Pad STRING to LENGTH using PADDING.
 If PADDING is nil, the space character is used.  If not nil, it
 should be a character.
@@ -330,16 +330,18 @@ should be a character.
 If STRING is longer than the absolute value of LENGTH, no padding
 is done.
 
-If LENGTH is positive, the padding is done to the end of the
-string, and if it's negative, padding is done to the start of the
+If START is nil (or not present), the padding is done to the end
+of the string, and non-nil, padding is done to the start of the
 string."
-  (let ((pad-length (- (abs length) (length string))))
+  (unless (natnump length)
+    (signal 'wrong-type-argument (list 'natnump length)))
+  (let ((pad-length (- length (length string))))
     (if (< pad-length 0)
         string
-      (concat (and (< length 0)
+      (concat (and start
                    (make-string pad-length (or padding ?\s)))
               string
-              (and (> length 0)
+              (and (not start)
                    (make-string pad-length (or padding ?\s)))))))
 
 (defun string-chop-newline (string)
diff --git a/test/lisp/emacs-lisp/subr-x-tests.el b/test/lisp/emacs-lisp/subr-x-tests.el
index 52b48095149..854d61ed28e 100644
--- a/test/lisp/emacs-lisp/subr-x-tests.el
+++ b/test/lisp/emacs-lisp/subr-x-tests.el
@@ -613,7 +613,7 @@
 (ert-deftest subr-string-pad ()
   (should (equal (string-pad "foo" 5) "foo  "))
   (should (equal (string-pad "foo" 5 ?-) "foo--"))
-  (should (equal (string-pad "foo" -5 ?-) "--foo"))
+  (should (equal (string-pad "foo" 5 ?- t) "--foo"))
   (should (equal (string-pad "foo" 2 ?-) "foo")))
 
 (ert-deftest subr-string-chop-newline ()
-- 
2.39.5