Function: string-rectangle

string-rectangle is an autoloaded, interactive and byte-compiled function defined in rect.el.gz.

Signature

(string-rectangle START END STRING)

Documentation

Replace rectangle contents with STRING on each line.

The length of STRING need not be the same as the rectangle width.

When called interactively and option rectangle-preview is non-nil, display the result as the user enters the string into the minibuffer.

Called from a program, takes three args; START, END and STRING.

View in manual

Probably introduced at or before Emacs version 19.20.

Key Bindings

Aliases

replace-rectangle (obsolete since 29.1)

Source Code

;; Defined in /usr/src/emacs/lisp/rect.el.gz
;;;###autoload
(defun string-rectangle (start end string)
  "Replace rectangle contents with STRING on each line.
The length of STRING need not be the same as the rectangle width.

When called interactively and option `rectangle-preview' is
non-nil, display the result as the user enters the string into
the minibuffer.

Called from a program, takes three args; START, END and STRING."
  (interactive
   (progn
     (make-local-variable 'rectangle--string-preview-state)
     (make-local-variable 'rectangle--inhibit-region-highlight)
     (let* ((buf (current-buffer))
            (win (if (eq (window-buffer) buf) (selected-window)))
            (start (region-beginning))
            (end (region-end))
            (rectangle--string-preview-state `(nil ,start ,end))
            ;; Rectangle-region-highlighting doesn't work well in the presence
            ;; of the preview overlays.  We could work harder to try and make
            ;; it work better, but it's easier to just disable it temporarily.
            (rectangle--inhibit-region-highlight t))
       (barf-if-buffer-read-only)
       (list start end
             (minibuffer-with-setup-hook
                 (lambda ()
                   (setq rectangle--string-preview-window win)
                   (add-hook 'minibuffer-exit-hook
                             #'rectangle--string-erase-preview nil t)
                   (add-hook 'post-command-hook
                             #'rectangle--string-preview nil t))
               (read-string (format-prompt
                             "String rectangle"
                             (or (car string-rectangle-history) ""))
                            nil 'string-rectangle-history
                            (car string-rectangle-history)
                            'inherit-input-method))))))
  ;; If we undo this change, we want to have the point back where we
  ;; are now, and not after the first line in the rectangle (which is
  ;; the first line to be changed by the following command).
  (unless (eq buffer-undo-list t)
    (push (point) buffer-undo-list))
  (goto-char
   (apply-on-rectangle 'string-rectangle-line start end string t)))