Liking cljdoc? Tell your friends :D

clojure.string

Clojure String utilities

It is poor form to (:use clojure.string). Instead, use require with :as to specify a prefix, e.g.

(ns your.namespace.here (:require [clojure.string :as str]))

Design notes for clojure.string:

  1. Strings are objects (as opposed to sequences). As such, the string being manipulated is the first argument to a function; passing nil will result in a NullPointerException unless documented otherwise. If you want sequence-y behavior instead, use a sequence.

  2. Functions are generally not lazy, and call straight to host methods where those are available and efficient.

  3. Functions take advantage of String implementation details to write high-performing loop/recurs instead of using higher-order functions. (This is not idiomatic in general-purpose application code.)

  4. When a function is documented to accept a string argument, it will take any implementation of the correct interface on the host platform. In Java, this is CharSequence, which is more general than String. In ordinary usage you will almost always pass concrete strings. If you are doing something unusual, e.g. passing a mutable implementation of CharSequence, then thread-safety is your responsibility.

Clojure String utilities

It is poor form to (:use clojure.string). Instead, use require
with :as to specify a prefix, e.g.

(ns your.namespace.here
  (:require [clojure.string :as str]))

Design notes for clojure.string:

1. Strings are objects (as opposed to sequences). As such, the
   string being manipulated is the first argument to a function;
   passing nil will result in a NullPointerException unless
   documented otherwise. If you want sequence-y behavior instead,
   use a sequence.

2. Functions are generally not lazy, and call straight to host
   methods where those are available and efficient.

3. Functions take advantage of String implementation details to
   write high-performing loop/recurs instead of using higher-order
   functions. (This is not idiomatic in general-purpose application
   code.)

4. When a function is documented to accept a string argument, it
   will take any implementation of the correct *interface* on the
   host platform. In Java, this is CharSequence, which is more
   general than String. In ordinary usage you will almost always
   pass concrete strings. If you are doing something unusual,
   e.g. passing a mutable implementation of CharSequence, then
   thread-safety is your responsibility.
raw docstring

blank?clj

(blank? s)

True if s is nil, empty, or contains only whitespace.

True if s is nil, empty, or contains only whitespace.
raw docstring

capitalizeclj

(capitalize s)

Converts first character of the string to upper-case, all other characters to lower-case.

Converts first character of the string to upper-case, all other
characters to lower-case.
raw docstring

ends-with?clj

(ends-with? s substr)

True if s ends with substr.

True if s ends with substr.
raw docstring

escapeclj

(escape s cmap)

Return a new string, using cmap to escape each character ch from s as follows:

If (cmap ch) is nil, append ch to the new string. If (cmap ch) is non-nil, append (str (cmap ch)) instead.

Return a new string, using cmap to escape each character ch
from s as follows:

If (cmap ch) is nil, append ch to the new string.
If (cmap ch) is non-nil, append (str (cmap ch)) instead.
raw docstring

includes?clj

(includes? s substr)

True if s includes substr.

True if s includes substr.
raw docstring

index-ofclj

(index-of s value)
(index-of s value from-index)

Return index of value (string or char) in s, optionally searching forward from from-index. Return nil if value not found.

Return index of value (string or char) in s, optionally searching
forward from from-index. Return nil if value not found.
raw docstring

joinclj

(join coll)
(join separator coll)

Returns a string of all elements in coll, as returned by (seq coll), separated by an optional separator.

Returns a string of all elements in coll, as returned by (seq coll),
separated by an optional separator.
raw docstring

last-index-ofclj

(last-index-of s value)
(last-index-of s value from-index)

Return last index of value (string or char) in s, optionally searching backward from from-index. Return nil if value not found.

Return last index of value (string or char) in s, optionally
searching backward from from-index. Return nil if value not found.
raw docstring

lower-caseclj

(lower-case s)

Converts string to all lower-case.

Converts string to all lower-case.
raw docstring

re-quote-replacementclj

(re-quote-replacement replacement)

Given a replacement string that you wish to be a literal replacement for a pattern match in replace or replace-first, do the necessary escaping of special characters in the replacement.

Given a replacement string that you wish to be a literal
replacement for a pattern match in replace or replace-first, do the
necessary escaping of special characters in the replacement.
raw docstring

replaceclj

(replace s match replacement)

Replaces all instance of match with replacement in s.

match/replacement can be:

string / string char / char pattern / (string or function of match).

See also replace-first.

The replacement is literal (i.e. none of its characters are treated specially) for all cases above except pattern / string.

For pattern / string, $1, $2, etc. in the replacement string are substituted with the string that matched the corresponding parenthesized group in the pattern. If you wish your replacement string r to be used literally, use (re-quote-replacement r) as the replacement argument. See also documentation for java.util.regex.Matcher's appendReplacement method.

Example: (clojure.string/replace "Almost Pig Latin" #"\b(\w)(\w+)\b" "$2$1ay") -> "lmostAay igPay atinLay"

Replaces all instance of match with replacement in s.

match/replacement can be:

string / string
char / char
pattern / (string or function of match).

See also replace-first.

The replacement is literal (i.e. none of its characters are treated
specially) for all cases above except pattern / string.

For pattern / string, $1, $2, etc. in the replacement string are
substituted with the string that matched the corresponding
parenthesized group in the pattern.  If you wish your replacement
string r to be used literally, use (re-quote-replacement r) as the
replacement argument.  See also documentation for
java.util.regex.Matcher's appendReplacement method.

Example:
(clojure.string/replace "Almost Pig Latin" #"\b(\w)(\w+)\b" "$2$1ay")
-> "lmostAay igPay atinLay"
raw docstring

replace-firstclj

(replace-first s match replacement)

Replaces the first instance of match with replacement in s.

match/replacement can be:

char / char string / string pattern / (string or function of match).

See also replace.

The replacement is literal (i.e. none of its characters are treated specially) for all cases above except pattern / string.

For pattern / string, $1, $2, etc. in the replacement string are substituted with the string that matched the corresponding parenthesized group in the pattern. If you wish your replacement string r to be used literally, use (re-quote-replacement r) as the replacement argument. See also documentation for java.util.regex.Matcher's appendReplacement method.

Example: (clojure.string/replace-first "swap first two words" #"(\w+)(\s+)(\w+)" "$3$2$1") -> "first swap two words"

Replaces the first instance of match with replacement in s.

match/replacement can be:

char / char
string / string
pattern / (string or function of match).

See also replace.

The replacement is literal (i.e. none of its characters are treated
specially) for all cases above except pattern / string.

For pattern / string, $1, $2, etc. in the replacement string are
substituted with the string that matched the corresponding
parenthesized group in the pattern.  If you wish your replacement
string r to be used literally, use (re-quote-replacement r) as the
replacement argument.  See also documentation for
java.util.regex.Matcher's appendReplacement method.

Example:
(clojure.string/replace-first "swap first two words"
                              #"(\w+)(\s+)(\w+)" "$3$2$1")
-> "first swap two words"
raw docstring

reverseclj

(reverse s)

Returns s with its characters reversed.

Returns s with its characters reversed.
raw docstring

splitclj

(split s re)
(split s re limit)

Splits string on a regular expression. Optional argument limit is the maximum number of splits. Not lazy. Returns vector of the splits.

Splits string on a regular expression.  Optional argument limit is
the maximum number of splits. Not lazy. Returns vector of the splits.
raw docstring

split-linesclj

(split-lines s)

Splits s on \n or \r\n.

Splits s on \n or \r\n.
raw docstring

starts-with?clj

(starts-with? s substr)

True if s starts with substr.

True if s starts with substr.
raw docstring

trimclj

(trim s)

Removes whitespace from both ends of string.

Removes whitespace from both ends of string.
raw docstring

trim-newlineclj

(trim-newline s)

Removes all trailing newline \n or return \r characters from string. Similar to Perl's chomp.

Removes all trailing newline \n or return \r characters from
string.  Similar to Perl's chomp.
raw docstring

trimlclj

(triml s)

Removes whitespace from the left side of string.

Removes whitespace from the left side of string.
raw docstring

trimrclj

(trimr s)

Removes whitespace from the right side of string.

Removes whitespace from the right side of string.
raw docstring

upper-caseclj

(upper-case s)

Converts string to all upper-case.

Converts string to all upper-case.
raw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close