Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the str Reference Manual, version 0.8, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:24:42 2018 GMT+0.
| • Introduction: | What str is all about | |
| • Systems: | The systems documentation | |
| • Files: | The files documentation | |
| • Packages: | The packages documentation | |
| • Definitions: | The symbols documentation | |
| • Indexes: | Concepts, functions, variables and data types |
(ql:quickload "str")
Why ?
modernity, simplicity and discoverability:
(str:trim s) instead of (string-trim '(#\Space #\Newline #\Backspace #\Tab #\Linefeed #\Page #\Return #\Rubout) s)),
or str:concat strings instead of an unusual format construct; one discoverable library instead of many;consistance and composability, where s is always the last argument, which makes it
easier to feed pipes and arrows.
The only dependency is cl-ppcre.
Table of Contents
Install with Quicklisp:
(ql:quickload :str)
Check its version:
(str:version)
To get a newer version, you need to update the Quicklisp dist (think of QL as Debian's apt rather than pip/npm/etc):
(ql:update-dist "quicklisp")
beware, this is a young and unstable library. (update v0.7) The functions implementation may change, but we shouldn't change the api.
(don't have a full Common Lisp development environment yet ? Get Portacle, a portable and multiplatform development environment shipping Emacs, Quicklisp, SBCL and Git).
(s)Remove whitespaces at the beginning and end of s.
(trim " rst ") ;; => "rst"
Also trim-left and trim-right.
Uses the built-in
string-trim
where whitespaces are '(#\Space #\Newline #\Backspace #\Tab #\Linefeed #\Page #\Return #\Rubout).
(separator list-of-strings)Join strings in list list-of-strings with separator in between.
(join " " '("foo" "bar" "baz")) ;; => "foo bar baz"
Uses a specific format syntax.
(&rest strings)Join strings into one.
(concat "f" "o" "o") ;; => "foo"
Simple call of the built-in concatenate.
(count s)Make a string of s repeated count times.
(repeat 3 "foo") ;; => "foofoofoo"
(start end s)Return the substring of s from start to end.
It uses subseq with differences:
start and end can be lower than 0 or bigger than the length of s.end can be nil or t to denote the end of the string.Examples:
(is "abcd" (substring 0 t "abcd") "t denotes the end of the string")
(is "abcd" (substring 0 nil "abcd") "nil too")
(is "abcd" (substring 0 100 "abcd") "end can be too large")
(is "abc" (substring 0 -1 "abcd") "end can be negative. Counts from the end.")
(is "" (substring 0 -100 "abcd") "end can be negative and too low")
(is "" (substring 100 1 "abcd") "start can be too big")
(is "abcd" (substring -100 4 "abcd") "start can also be too low")
(is "" (substring 2 1 "abcd") "start is bigger than end")
(s)Return list of words, which were delimited by whitespace.
(strings)Join the list of strings with a whitespace.
(s)Split string by newline character and return list of lines.
(strings)Join the list of strings with a newline character.
(separator s &key omit-nulls)Split into subtrings (unlike cl-ppcre, without a regexp). If
omit-nulls is non-nil, zero-length substrings are omitted.
(split "+" "foo++bar") ;; => ("foo" "" "bar")
(split "+" "foo++bar" :omit-nulls t) ;; => ("foo" "bar")
Wrapper around cl-ppcre:split but:
(cl-ppcre:split "," ",a,b,,c,") ;; => ("" "a" "b" "" "c")
and we return a trailing "":
(split "," ",a,b,,c,") ;; => ("" "a" "b" "" "c" "")
Because it is a common pattern and it can be clearer than an option coming after many parenthesis.
(filename)Read the file and return its content as a string.
Example: (str:from-file "path/to/file.txt").
:external-format: if nil, the system default. Can be bound to :utf-8.
But you might just call
uiop's uiop:read-file-string
directly.
There is also uiop:read-file-lines.
(filename s)Write the string s to the file filename. If the file does not
exist, create it, if it already exists, replace it.
Options:
:if-does-not-exist: :create (default), :error:if-exists: :supersede (default), :append, :overwrite, :rename, :error,...Returns the string written to file.
(s)True if s is nil or the empty string:
(empty? nil) ;; => T
(empty? "") ;; => T
(empty? " ") ;; => NIL
(s)True if s is empty or only contains whitespaces.
(blankp "") ;; => T
(blankp " ") ;; => T
(emptyp " ") ;; => NIL
(start s &key ignore-case)True if s starts with the substring start, nil otherwise. Ignore
case by default.
(starts-with? "foo" "foobar") ;; => T
(starts-with? "FOO" "foobar") ;; => NIL
(starts-with? "FOO" "foobar" :ignore-case t) ;; => T
Calls string= or string-equal depending on the case, with their
:start and :end delimiters.
(end s &key ignore-case)True if s ends with the substring end. Ignore case by default.
(ends-with? "bar" "foobar") ;; => T
(substring s &key (ignore-case nil))Return true if s contains substring, nil otherwise. Ignore the
case with :ignore-case t (don't ignore by default).
Based on a simple call to the built-in search (which returns the
position of the substring).
(old new s)Replace old by new (no regexs) in s.
(replace-all "a" "o" "faa") ;; => "foo"
Uses cl-ppcre:regex-replace-all but quotes the user input to not treat it as a regex.
(list-of-strings) new in v0.5Find the common prefix between strings.
Example: (str:common-prefix '(\"foobar\" \"foozz\")) => "foo"
Uses the built-in mismatch, that returns the position at which
the strings fail to match.
Return a string or nil when the input is the void list.
A case-like macro that works with strings (CL's case only works with symbols).
Example:
(str:string-case input
("foo" (do something))
(nil (print "input is nil")
(otherwise (print "non of the previous forms was caught.")))
You might also like pattern matching. The example below with optima is very similar:
(optima:match "hey"
("hey" (print "it matched"))
(otherwise :nothing))
Note that there is also http://quickdocs.org/string-case/.
string-caseversionsplit-omit-nulls (QL, january 2018)common-prefixfrom-file and to-file.substring.Test with prove.
Inspired by the famous Emacs Lisp's s.el.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The str system: |
vindarel <vindarel@mailz.org>
vindarel <vindarel@mailz.org>
(:git "git@github.com:vindarel/cl-s.git")
MIT
Modern, consistent and terse Common Lisp string manipulation library.
# A modern and consistent Common Lisp string manipulation library
(ql:quickload "str")
Why ?
* modernity, simplicity and discoverability:
- ‘(str:trim s)‘ instead of ‘ (string-trim ’(#\Space #\Newline #\Backspace #\Tab #\Linefeed #\Page #\Return #\Rubout) s))‘,
or ‘str:concat strings‘ instead of an unusual ‘format‘ construct; one discoverable library instead of many;
* consistance and composability, where ‘s‘ is always the last argument, which makes it
easier to feed pipes and arrows.
The only dependency is ‘cl-ppcre‘.
<!– markdown-toc start - Don’t edit this section. Run M-x markdown-toc-generate-toc again –>
**Table of Contents**
- [A modern and consistent Common Lisp string manipulation library](#a-modern-and-consistent-common-lisp-string-manipulation-library)
- [Install](#install)
- [Functions](#functions)
- [Tweak whitespace](#tweak-whitespace)
- [trim ‘(s)‘](#trim-s)
- [To longer strings](#to-longer-strings)
- [join ‘(separator list-of-strings)‘](#join-separator-list-of-strings)
- [concat ‘(&rest strings)‘](#concat-rest-strings)
- [repeat ‘(count s)‘](#repeat-count-s)
- [To shorter strings](#to-shorter-strings)
- [Substring ‘(start end s)‘](#substring-start-end-s)
- [To and from lists](#to-and-from-lists)
- [words ‘(s)‘](#words-s)
- [unwords ‘(strings)‘](#unwords-strings)
- [lines ‘(s)‘](#lines-s)
- [unlines ‘(strings)‘](#unlines-strings)
- [split ‘(separator s &key omit-nulls)‘](#split-separator-s-key-omit-nulls)
- [split-omit-nulls (in v0.6, QL january 2018)](#split-omit-nulls–in-v06-ql-january-2018)
- [To and from files (experimental in v0.4)](#to-and-from-files-experimental-in-v04)
- [from-file ‘(filename)‘](#from-file-filename)
- [to-file ‘(filename s)‘](#to-file-filename-s)
- [Predicates](#predicates)
- [empty?, emptyp ‘(s)‘](#empty-emptyp-s)
- [blank?, blankp ‘(s)‘](#blank-blankp-s)
- [starts-with?, starts-with-p ‘(start s &key ignore-case)‘](#starts-with-starts-with-p-start-s-key-ignore-case)
- [ends-with?, ends-with-p ‘(end s &key ignore-case)‘](#ends-with-ends-with-p-end-s-key-ignore-case)
- [contains?, containsp ‘(substring s &key (ignore-case nil))‘](#contains-containsp-substring-s-key-ignore-case-nil)
- [Others](#others)
- [replace-all ‘(old new s)‘](#replace-all-old-new-s)
- [common-prefix ‘(list-of-strings)‘ new in v0.5](#common-prefix-list-of-strings-new-in-v05)
- [Macros](#macros)
- [string-case](#string-case)
- [Changelog](#changelog)
- [Dev and test](#dev-and-test)
- [See also](#see-also)
<!– markdown-toc end –>
## Install
Install with [Quicklisp](https://www.quicklisp.org/beta/):
(ql:quickload :str)
Check its version:
(str:version)
To get a newer version, you need to update the Quicklisp dist (think
of QL as Debian’s apt rather than pip/npm/etc):
(ql:update-dist "quicklisp")
beware, this is a young and unstable library. (update v0.7) The
functions implementation may change, but we shouldn’t change the api.
(don’t have a full Common Lisp development environment yet ? Get
[Portacle](https://shinmera.github.io/portacle/), a portable and
multiplatform development environment shipping Emacs, Quicklisp, SBCL
and Git).
## Functions
### Tweak whitespace
#### trim ‘(s)‘
Remove whitespaces at the beginning and end of ‘s‘.
“‘cl
(trim " rst ") ;; => "rst"
“‘
Also ‘trim-left‘ and ‘trim-right‘.
Uses the built-in
[string-trim](https://lispcookbook.github.io/cl-cookbook/strings.html#trimming-blanks-from-the-ends-of-a-string)
where whitespaces are ‘’(#\Space #\Newline #\Backspace #\Tab #\Linefeed #\Page #\Return #\Rubout)‘.
### To longer strings
#### join ‘(separator list-of-strings)‘
Join strings in list ‘list-of-strings‘ with ‘separator‘ in between.
“‘cl
(join " " ’("foo" "bar" "baz")) ;; => "foo bar baz"
“‘
Uses a specific [format](http://jtra.cz/stuff/lisp/sclr/format.html) syntax.
#### concat ‘(&rest strings)‘
Join strings into one.
“‘cl
(concat "f" "o" "o") ;; => "foo"
“‘
Simple call of the built-in [concatenate](https://lispcookbook.github.io/cl-cookbook/strings.html#concatenating-strings).
#### repeat ‘(count s)‘
Make a string of ‘s‘ repeated ‘count‘ times.
“‘cl
(repeat 3 "foo") ;; => "foofoofoo"
“‘
### To shorter strings
#### Substring ‘(start end s)‘
Return the substring of ‘s‘ from ‘start‘ to ‘end‘.
It uses ‘subseq‘ with differences:
* argument order, s at the end
* ‘start‘ and ‘end‘ can be lower than 0 or bigger than the length of s.
* for convenience ‘end‘ can be nil or t to denote the end of the string.
Examples:
“‘lisp
(is "abcd" (substring 0 t "abcd") "t denotes the end of the string")
(is "abcd" (substring 0 nil "abcd") "nil too")
(is "abcd" (substring 0 100 "abcd") "end can be too large")
(is "abc" (substring 0 -1 "abcd") "end can be negative. Counts from the end.")
(is "" (substring 0 -100 "abcd") "end can be negative and too low")
(is "" (substring 100 1 "abcd") "start can be too big")
(is "abcd" (substring -100 4 "abcd") "start can also be too low")
(is "" (substring 2 1 "abcd") "start is bigger than end")
“‘
### To and from lists
#### words ‘(s)‘
Return list of words, which were delimited by whitespace.
#### unwords ‘(strings)‘
Join the list of strings with a whitespace.
#### lines ‘(s)‘
Split string by newline character and return list of lines.
#### unlines ‘(strings)‘
Join the list of strings with a newline character.
#### split ‘(separator s &key omit-nulls)‘
Split into subtrings (unlike cl-ppcre, without a regexp). If
‘omit-nulls‘ is non-nil, zero-length substrings are omitted.
“‘cl
(split "+" "foo++bar") ;; => ("foo" "" "bar")
(split "+" "foo++bar" :omit-nulls t) ;; => ("foo" "bar")
“‘
Wrapper around [cl-ppcre:split](http://weitz.de/cl-ppcre/#split) but:
- our separator is a simple string, where cl-ppcre takes a regexp,
- we fix an inconsistency:
“‘
(cl-ppcre:split "," ",a,b,,c,") ;; => ("" "a" "b" "" "c")
“‘
and we return a trailing ‘""‘:
(split "," ",a,b,,c,") ;; => ("" "a" "b" "" "c" "")
#### split-omit-nulls (in v0.6, QL january 2018)
Because it is a common pattern and it can be clearer than an option
coming after many parenthesis.
### To and from files (experimental in v0.4)
#### from-file ‘(filename)‘
Read the file and return its content as a string.
Example: ‘(str:from-file "path/to/file.txt")‘.
‘:external-format‘: if nil, the system default. Can be bound to ‘:utf-8‘.
But you might just call
[uiop’s ‘uiop:read-file-string‘](https://github.com/fare/asdf/blob/master/uiop/stream.lisp#L445)
directly.
There is also ‘uiop:read-file-lines‘.
#### to-file ‘(filename s)‘
Write the string ‘s‘ to the file ‘filename‘. If the file does not
exist, create it, if it already exists, replace it.
Options:
* ‘:if-does-not-exist‘: ‘:create‘ (default), ‘:error‘
* ‘:if-exists‘: ‘:supersede‘ (default), ‘:append‘, ‘:overwrite‘, ‘:rename‘, ‘:error‘,...
Returns the string written to file.
### Predicates
#### empty?, emptyp ‘(s)‘
True if ‘s‘ is nil or the empty string:
“‘cl
(empty? nil) ;; => T
(empty? "") ;; => T
(empty? " ") ;; => NIL
“‘
#### blank?, blankp ‘(s)‘
True if ‘s‘ is empty or only contains whitespaces.
(blankp "") ;; => T
(blankp " ") ;; => T
(emptyp " ") ;; => NIL
#### starts-with?, starts-with-p ‘(start s &key ignore-case)‘
True if ‘s‘ starts with the substring ‘start‘, nil otherwise. Ignore
case by default.
(starts-with? "foo" "foobar") ;; => T
(starts-with? "FOO" "foobar") ;; => NIL
(starts-with? "FOO" "foobar" :ignore-case t) ;; => T
Calls ‘string=‘ or ‘string-equal‘ depending on the case, with their
‘:start‘ and ‘:end‘ delimiters.
#### ends-with?, ends-with-p ‘(end s &key ignore-case)‘
True if ‘s‘ ends with the substring ‘end‘. Ignore case by default.
(ends-with? "bar" "foobar") ;; => T
#### contains?, containsp ‘(substring s &key (ignore-case nil))‘
Return true if ‘s‘ contains ‘substring‘, nil otherwise. Ignore the
case with ‘:ignore-case t‘ (don’t ignore by default).
Based on a simple call to the built-in ‘search‘ (which returns the
position of the substring).
### Others
#### replace-all ‘(old new s)‘
Replace ‘old‘ by ‘new‘ (no regexs) in ‘s‘.
“‘cl
(replace-all "a" "o" "faa") ;; => "foo"
“‘
Uses
[cl-ppcre:regex-replace-all](http://weitz.de/cl-ppcre/#regex-replace-all)
but quotes the user input to not treat it as a regex.
#### common-prefix ‘(list-of-strings)‘ new in v0.5
Find the common prefix between strings.
Example: ‘(str:common-prefix ’(\"foobar\" \"foozz\"))‘ => \"foo\"
Uses the built-in ‘mismatch‘, that returns the position at which
the strings fail to match.
Return a string or nil when the input is the void list.
## Macros
### string-case (new in v0.8, Quicklisp end of february 2018)
A case-like macro that works with strings (CL’s case only works with symbols).
Example:
~~~lisp
(str:string-case input
("foo" (do something))
(nil (print "input is nil")
(otherwise (print "non of the previous forms was caught.")))
~~~
You might also like pattern matching. The example below with
[optima](https://github.com/m2ym/optima) is very similar:
~~~lisp
(optima:match "hey"
("hey" (print "it matched"))
(otherwise :nothing))
~~~
Note that there is also http://quickdocs.org/string-case/.
## Changelog
* 0.8 added ‘string-case‘
* 0.7 added ‘version‘
* 0.6 added ‘split-omit-nulls‘ (QL, january 2018)
* 0.5 added ‘common-prefix‘
* 0.4 added ‘from-file‘ and ‘to-file‘.
* 0.3 added ‘substring‘.
## Dev and test
Test with [prove](https://github.com/fukamachi/prove).
## See also
* [cl-strings](https://github.com/diogoalexandrefranco/cl-strings), a
similar (discovered afterwards), maybe more complete library, that
does not use established libraries as dependencies as we do (with
*potential* implementation
[issues](https://github.com/diogoalexandrefranco/cl-strings/issues/2)).
* [cl-change-case](https://github.com/rudolfochrist/cl-change-case) to
convert strings between camelCase, param-case, snake_case and more.
* the [Common Lisp Cookbook](https://lispcookbook.github.io/cl-cookbook/strings.html), strings page.
Inspired by the famous Emacs Lisp’s [s.el](https://github.com/magnars/s.el).
0.8
cl-ppcre
str.asd (file)
str.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files: |
| • The str.asd file: | ||
| • The str/str.lisp file: |
Next: The str/str<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
str.asd
str (system)
Previous: The str<dot>asd file, Up: Lisp files [Contents][Index]
str (system)
str.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The str package: |
str.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions: | ||
| • Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables: | ||
| • Exported macros: | ||
| • Exported functions: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
A case-like macro that works with strings (case works only with symbols).
Example:
(str:string-case input
("foo" (do something))
(nil (print "input is nil")
(otherwise (print "none of the previous forms was caught")))
You might also like pattern matching. The example below with optima is very similar:
(optima:match "hey"
("hey" (print "it matched"))
(otherwise :nothing))
Note that there is also http://quickdocs.org/string-case/.
Previous: Exported macros, Up: Exported definitions [Contents][Index]
Find the common prefix between strings.
Uses the built-in ‘mismatch’, that returns the position at which
the strings fail to match.
Example: ‘(str:common-prefix ’("foobar" "foozz"))‘ => "foo"
- items: list of strings
- Return: a string.
Join all the string arguments into one string.
Return ‘t‘ if ‘s‘ contains ‘substring‘, nil otherwise. Ignore the case with ‘:ignore-case t‘. A simple call to the built-in ‘search‘ (which returns the position of the substring).
Return ‘t‘ if ‘s‘ contains ‘substring‘, nil otherwise. Ignore the case with ‘:ignore-case t‘. A simple call to the built-in ‘search‘ (which returns the position of the substring).
Return t if s ends with the substring ’end’, nil otherwise.
Return t if s ends with the substring ’end’, nil otherwise.
Read the file and return its content as a string.
From v0.7 simply uses uiop:read-file-string. There is also read-file-lines.
Example: (str:from-file "path/to/file.txt" :external-format :utf-8)
- external-format: if nil, the system default. Can be bound to :utf-8.
Split the string by newline characters and return a list of lines.
Make a string of S repeated COUNT times.
Replace ‘old‘ by ‘new‘ in ‘s‘. Arguments are not regexs.
Split s into substring by separator (cl-ppcre takes a regex, we do not).
Call split with :omit-nulls to t.
Can be clearer in certain situations.
Return t if s starts with the substring ’start’, nil otherwise.
Return t if s starts with the substring ’start’, nil otherwise.
Return the substring of ‘s’ from ‘start’ to ‘end’.
It uses ‘subseq’ with differences:
- argument order, s at the end
- ‘start’ and ‘end’ can be lower than 0 or bigger than the length of s.
- for convenience ‘end’ can be nil or t to denote the end of the string.
Write string ‘s’ to file ‘pathname’. If the file does not exist, create it (use ‘:if-does-not-exist’), if it already exists, replace its content (‘:if-exists’).
Returns the string written to file.
Remove whitespaces at the beginning and end of s.
@begin[lang=lisp](code)
(trim " foo ") ;; => "foo"
@end(code)
Join the list of strings with a newline character.
Join the list of strings with a whitespace.
Return list of words, which were delimited by white space. If the optional limit is 0 (the default), trailing empty strings are removed from the result list (see cl-ppcre).
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables: | ||
| • Internal functions: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index: | ||
| • Function index: | ||
| • Variable index: | ||
| • Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L S |
|---|
| Jump to: | F L S |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | B C E F J L M R S T U V W |
|---|
| Jump to: | B C E F J L M R S T U V W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
S |
|---|
| Jump to: | *
+
S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | P S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| P | |||
Package, str: | The str package | ||
| | |||
| S | |||
str: | The str system | ||
str: | The str package | ||
System, str: | The str system | ||
| | |||
| Jump to: | P S |
|---|