The cl-str Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-str Reference Manual

This is the cl-str Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 14:03:41 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

A modern and consistent Common Lisp string manipulation library

(ql:quickload "str")

Why ?

Table of Contents

Install

Install with Quicklisp:

(ql:quickload :str)

beware, this is a young and unstable library.

(don't have a full Common Lisp development environment yet ? Get 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.

(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).

To longer strings

join (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.

concat (&rest strings)

Join strings into one.

(concat "f" "o" "o") ;; => "foo"

Simple call of the built-in concatenate.

repeat (count s)

Make a string of s repeated count times.

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

To shorter strings

Substring (start end s) - new in 0.3

Return the substring of s from start to end.

It uses subseq with differences:

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")

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.

(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" "")

Predicates

empty?, emptyp (s)

True if s is nil or the empty string:

  (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.

(replace-all "a" "o" "faa") ;; => "foo"

Uses cl-ppcre:regex-replace-all but quotes the user input to not treat it as a regex.

Dev and test

Test with prove.

See also

Inspired by the famous Emacs Lisp's s.el.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 str

Maintainer

vindarel <ehvince@mailz.org>

Author

vindarel <ehvince@mailz.org>

Home Page

https://github.com/vindarel/cl-str

Source Control

(:git "git@github.com:vindarel/cl-s.git")

Bug Tracker

https://github.com/vindarel/cl-str/issues

License

MIT

Description

Modern, consistent and terse Common Lisp string manipulation library.

Long Description

# 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.

<!– 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)‘ - new in 0.3](#substring-start-end-s—new-in-03)
- [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)
- [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-old-new-s)
- [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)

beware, this is a young and unstable library.

(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)‘ - new in 0.3

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" "")

### 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.

## 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).

Version

0.1

Dependency

cl-ppcre

Source

str.asd (file)

Component

str.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 str.asd

Location

str.asd

Systems

str (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 str/str.lisp

Parent

str (system)

Location

str.lisp

Packages

str

Exported Definitions
Internal Definitions

*whitespaces* (special variable)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 str

Source

str.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

*whitespaces* (special variable)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: blank? S

Is s nil or only contains whitespaces ?

Package

str

Source

str.lisp (file)

Function: blankp S

Is s nil or only contains whitespaces ?

Package

str

Source

str.lisp (file)

Function: concat &rest STRINGS

Join all the string arguments into one string.

Package

str

Source

str.lisp (file)

Function: contains? SUBSTRING S &key IGNORE-CASE

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).

Package

str

Source

str.lisp (file)

Function: containsp SUBSTRING S &key IGNORE-CASE

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).

Package

str

Source

str.lisp (file)

Function: empty? S

Is s nil or the empty string ?

Package

str

Source

str.lisp (file)

Function: emptyp S

Is s nil or the empty string ?

Package

str

Source

str.lisp (file)

Function: ends-with-p END S &key IGNORE-CASE

Return t if s ends with the substring ’end’, nil otherwise.

Package

str

Source

str.lisp (file)

Function: ends-with? END S &key IGNORE-CASE

Return t if s ends with the substring ’end’, nil otherwise.

Package

str

Source

str.lisp (file)

Function: join SEPARATOR STRINGS
Package

str

Source

str.lisp (file)

Function: lines S &key OMIT-NULLS

Split the string by newline characters and return a list of lines.

Package

str

Source

str.lisp (file)

Function: repeat COUNT S

Make a string of S repeated COUNT times.

Package

str

Source

str.lisp (file)

Function: replace-all OLD NEW S

Replace ‘old‘ by ‘new‘ in ‘s‘. Arguments are not regexs.

Package

str

Source

str.lisp (file)

Function: split SEPARATOR S &key OMIT-NULLS

Split s into substring by separator (cl-ppcre takes a regex, we do not).

Package

str

Source

str.lisp (file)

Function: starts-with-p START S &key IGNORE-CASE

Return t if s starts with the substring ’start’, nil otherwise.

Package

str

Source

str.lisp (file)

Function: starts-with? START S &key IGNORE-CASE

Return t if s starts with the substring ’start’, nil otherwise.

Package

str

Source

str.lisp (file)

Function: 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.

Package

str

Source

str.lisp (file)

Function: trim S

Remove whitespaces at the beginning and end of s. @begin[lang=lisp](code)
(trim " foo ") ;; => "foo"
@end(code)

Package

str

Source

str.lisp (file)

Function: trim-left S

Remove whitespaces at the beginning of s.

Package

str

Source

str.lisp (file)

Function: trim-right S

Remove whitespaces at the end of s.

Package

str

Source

str.lisp (file)

Function: unlines STRINGS

Join the list of strings with a newline character.

Package

str

Source

str.lisp (file)

Function: unwords STRINGS

Join the list of strings with a whitespace.

Package

str

Source

str.lisp (file)

Function: words S &key LIMIT

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).

Package

str

Source

str.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *whitespaces*
Package

str

Source

str.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, str.asd: The str<dot>asd file
File, Lisp, str/str.lisp: The str/str<dot>lisp file

L
Lisp File, str.asd: The str<dot>asd file
Lisp File, str/str.lisp: The str/str<dot>lisp file

S
str.asd: The str<dot>asd file
str/str.lisp: The str/str<dot>lisp file

Jump to:   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   C   E   F   J   L   R   S   T   U   W  
Index Entry  Section

B
blank?: Exported functions
blankp: Exported functions

C
concat: Exported functions
contains?: Exported functions
containsp: Exported functions

E
empty?: Exported functions
emptyp: Exported functions
ends-with-p: Exported functions
ends-with?: Exported functions

F
Function, blank?: Exported functions
Function, blankp: Exported functions
Function, concat: Exported functions
Function, contains?: Exported functions
Function, containsp: Exported functions
Function, empty?: Exported functions
Function, emptyp: Exported functions
Function, ends-with-p: Exported functions
Function, ends-with?: Exported functions
Function, join: Exported functions
Function, lines: Exported functions
Function, repeat: Exported functions
Function, replace-all: Exported functions
Function, split: Exported functions
Function, starts-with-p: Exported functions
Function, starts-with?: Exported functions
Function, substring: Exported functions
Function, trim: Exported functions
Function, trim-left: Exported functions
Function, trim-right: Exported functions
Function, unlines: Exported functions
Function, unwords: Exported functions
Function, words: Exported functions

J
join: Exported functions

L
lines: Exported functions

R
repeat: Exported functions
replace-all: Exported functions

S
split: Exported functions
starts-with-p: Exported functions
starts-with?: Exported functions
substring: Exported functions

T
trim: Exported functions
trim-left: Exported functions
trim-right: Exported functions

U
unlines: Exported functions
unwords: Exported functions

W
words: Exported functions

Jump to:   B   C   E   F   J   L   R   S   T   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*whitespaces*: Internal special variables

S
Special Variable, *whitespaces*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

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