cl-str

Install the library using Quicklisp with (ql:quickload :str).

When using the library in your own projects, add :str to your .asd file's dependencies. It is recommended to access functions using the str: prefix (e.g., str:trim) rather than using :use :str in your package to avoid name collisions.

To check the installed version, use (str:version). If you need to update to a newer version, update your Quicklisp distribution using (ql:update-dist "quicklisp").

(ql:quickload :str)

;; Check version
(str:version)

;; Update Quicklisp to get newer versions
(ql:update-dist "quicklisp")

Use these functions to modify parts of a string:

• str:replace-first: Replaces only the first occurrence of old with new. Use :regex t to treat old as a regular expression.
• str:replace-all: Replaces all occurrences of old with new.
• str:replace-using: Replaces multiple patterns using an association list where elements alternate between old and new values.
• str:remove-punctuation: Removes punctuation, replacing them with a replacement (default: space) and stripping continuous whitespace.

(str:replace-first "a" "o" "faa") ;; => "foa"
(str:replace-all "fo+" "frob" "foofoo bar" :regex t) ;; => "frobfrob bar"

(str:replace-using (list "%phone%" "987") "call %phone%") ;; => "call 987"

(str:remove-punctuation "I say: - 'Hello, world?'") ;; => "I say Hello world"

Use str:insert to place a string or character at a specific index. If the index is out of bounds, the original string is returned unchanged.

(str:insert "l" 2 "helo") ;; => "hello"
(str:insert "o" 99 "hell") ;; => "hell"

To combine a list of strings with a separator, use str:join. The separator can be a string or a character. To simply concatenate a sequence of strings without a separator, use str:concat (which wraps the built-in concatenate).

(str:join " " '("foo" "bar" "baz")) ;; => "foo bar baz"
(str:join #\Space '("foo" "bar" "baz")) ;; => "foo bar baz"
(str:concat "f" "o" "o") ;; => "foo"

Use str:from-file to read a file's content into a string. You can specify the :external-format (e.g., :utf-8).

Use str:to-file to write a string to a file. It can create a file if it doesn't exist or handle existing files via :if-exists (options: :supersede, :append, :overwrite, :rename, :error).

(str:from-file "path/to/file.txt")

(str:to-file "output.txt" "content")

Use str:repeat to create a new string consisting of the input string repeated count times. For very large outputs (>10,000 characters), the function generates the string in chunks to prevent stack/heap overflows.

(str:repeat 3 "foo") ;; => "foofoofoo"

Use str:trim, str:trim-left, or str:trim-right to remove characters from the beginning or end of a string. By default, these functions remove standard whitespace characters. You can provide a custom :char-bag (a string or list of characters) to trim specific characters instead.

(str:trim "  rst  ") ;; => "rst"
(str:trim "+-*foo-bar*-+" :char-bag "+-*") => "foo-bar"
(str:trim "afood" :char-bag (concat "a" "d")) => "foo"

Use str:pad, str:pad-left, str:pad-right, or str:pad-center to fill a string until it reaches a target length.

• :pad-side: Can be :right (default), :left, or :center.
• :pad-char: The character or string used for padding (defaults to #\Space).

If the string is already longer than the target length, the original string is returned.

(str:pad 10 "foo") ;; => "foo       "
(str:pad 10 "foo" :pad-side :center :pad-char "+") ;; => "+++foo++++"

The str:ensure family of functions ensures a string meets certain structural requirements by adding the necessary characters if they are missing.

• str:ensure: A multi-purpose function that uses :wrapped-in, :prefix, or :suffix keys. Note that :wrapped-in takes precedence over :prefix and :suffix if both are provided.
• str:ensure-prefix: Ensures the string starts with the specified value.
• str:ensure-suffix: Ensures the string ends with the specified value.
• str:ensure-wrapped-in: Ensures the string both starts and ends with the specified value.

(str:ensure "abc" :wrapped-in "/")  ;; => "/abc/"
(str:ensure "/abc" :prefix "/")    ;; => "/abc" (no change)
(str:ensure "/abc" :suffix "/")    ;; => "/abc/" (added suffix)
(str:ensure-prefix "/" "abc/")     ;; => "/abc/"
(str:ensure-wrapped-in "/" "abc")   ;; => "/abc/"

Use str:collapse-whitespaces to ensure there is only a single space character between words and to remove all newline characters from a string.

(str:collapse-whitespaces "foo  bar\n\n  baz")
;; => "foo bar baz"

Use str:fit to ensure a string is exactly a certain length. It combines shorten and pad logic:

• If the string is too long, it is truncated with an ellipsis.
• If the string is too short, it is padded using the :pad-side and :pad-char settings.

It accepts the same keyword arguments as str:shorten and str:pad.

(str:fit 10 "hello" :pad-char "+")      ;; => "hello+++++"
(str:fit 10 "hello world" :ellipsis "…") ;; => "hello wor…"

Use str:shorten to truncate a string if it exceeds a specified length. By default, it appends an ellipsis (...). The total length of the resulting string will be the specified len, which includes the length of the ellipsis.

You can customize the ellipsis using the :ellipsis keyword or by setting the global *ellipsis* variable.

(str:shorten 8 "hello world")           ;; => "hello..."
(str:shorten 8 "hello world" :ellipsis "-") ;; => "hello w-"

(let ((*ellipsis* "-"))
  (str:shorten 8 "hello world"))        ;; => "hello w-"