cuerdas

Introduction

The missing clojure(script) string manipulation library.

La guitarra,
hace llorar a los sueños.
El sollozo de las almas
perdidas,
se escapa por su boca
redonda.
Y como la tarántula
teje una gran estrella
para cazar suspiros,
que flotan en su negro
aljibe de madera.

— Federico García Lorca
Las Seis Cuerdas

Install

The simplest way to use cuerdas in a clojure project, is by including it in the dependency vector on your project.clj file:

[cuerdas "0.3.0"]

Quick start

Import the namespace

(ns my.namespace
  (:require [cuerdas.core :as str]))

Use its functions

(str/strip-tags "<p>just <b>some</b> text</p>")
;; => "just some text"

(str/strip-tags "<p>just <b>some</b> text</p>" ["p"])
;; => "just <b>some</b> text"

Reference

contains?

Determines whether a string contains a substring.

(str/contains? "foobar" "bar")
;; => true

(str/contains? "foobar" nil)
;; => false

(str/contains? nil nil)
;; => false

starts-with?

Check if the string starts with prefix.

Alias: startswith?

(str/startswith? "foobar" "foo")
;; => true

(str/startswith? "foobar" nil)
;; => false

(str/startswith? nil "foo")
;; => false

ends-with?

Check if the string ends with suffix.

Alias: endswith?

(str/endswith? "foobar" "bar")
;; => true

(str/endswith? "foobar" nil)
;; => false

(str/endswith? nil "bar")
;; => false

empty?

Check if the string is empty.

(str/empty? "foobar")
;; => false

(str/empty? nil)
;; => true

(str/empty? "")
;; => true

(str/empty? " ")
;; => false

blank?

Check if the string is empty or contains only whitespaces.

(str/blank? "foobar")
;; => false

(str/blank? "   ")
;; => true

(str/blank? "")
;; => true

(str/blank? nil)
;; => true

upper

Converts string to all upper-case.

(str/upper "foobar")
;; => "FOOBAR"

(str/upper nil)
;; => nil

lower

Converts string to all lower-case.

(str/lower "FOO")
;; => "foo"

(str/lower nil)
;; => nil

repeat

Repeats string N times.

(str/repeat "a" 3)
;; => "aaa"

(str/repeat nil 3)
;; => nil

trim

Removes whitespace or specified characters from both ends of string.

Alias: strip

(str/trim " foo ")
;; => "foo"

(str/trim "-foo-", "-")
;; => "foo"

(str/trim nil)
;; => nil

ltrim

Removes whitespace or specified characters from left side of string.

Alias: lstrip

(str/ltrim " foo ")
;; => "foo "

(str/ltrim "-foo-", "-")
;; => "foo-"

(str/ltrim nil)
;; => nil

rtrim

Removes whitespace or specified characters from right side of string.

Alias: rstrip

(str/rtrim " foo ")
;; => " foo"

(str/rtrim "-foo-", "-")
;; => "-foo"

(str/rtrim nil)
;; => nil

strip-prefix

Remove prefix from string if it matches exactly or leave the string untouched.

(str/strip-prefix nil nil)
;; => nil

(str/strip-prefix "a" nil)
;; => "a"

(str/strip-prefix "-=a" "-=")
;; => "a"

strip-suffix

Remove suffix from string if it matches exactly or leave the string untouched.

(str/strip-suffix nil nil)
;; => nil

(str/strip-suffix "a" nil)
;; => "a"

(str/strip-suffix "a=-" "=-")
;; => "a"

collapse-whitespace

Converts all adjacent whitespace characters to a single space.

(str/collapse-whitespace "a\n\nb")
;; => "a b"

(str/collapse-whitespace nil)
;; => nil

prune

Truncates a string to certain left and adds "…" if necesary. Making sure that the pruned string does not exceed the original length and avoid half-chopped words when truncating.

(str/prune "Hello World" 5)
;; => "Hello..."

(str/prune "Hello World" 8)
;; => "Hello..."

(str/prune "Hello World" 11 " (...)")
;; => "Hello (...)"

(str/prune nil 5)
;; => nil

join

Join strings together with given separator.

(str/join ["foo" "bar"])
;; => "foobar"

(str/join "," ["foo" "bar"])
;; => "foo,bar"

split

Splits a string on a separator a limited number of times. The separator can be a string or RegExp instance.

(str/split "1 2 3")
;; => ["1" "2" "3"]

(str/split "1 2 3" " ")
;; => ["1" "2" "3"])

(str/split "1 2 3" #"\s")
;; => ["1" "2" "3"]

(str/split "1 2 3" #"\s" 2)
;; => ["1" "2 3"]

(str/split nil)
;; => nil

reverse

Return strign reverted

(str/reverse "bar")
;; => "rab"

(str/reverse nil)
;; => nil

chars

Returns a seq of char strings from string.

(str/chars "bar")
;; => ["b" "a" "r"]

(str/chars nil)
;; => nil

lines

Return a list of the lines in the string.

(str/lines "foo\nbar")
;; => ["foo" "bar"]

(str/lines nil)
;; => nil

unlines

Joins a list of strings with a newline separator. This operation is the opposite of lines.

(str/unlines ["foo" "nbar"])
;; => "foo\nbar"

(str/unlines nil)
;; => nil

slice

Extracts a section of a string and returns a new string.

(str/slice "123" 1)
;; => "23"

(str/slice "1234" 1 3)
;; => "23"

(str/slice nil 1 3)
;; => nil

replace

Replaces all instance of match with replacement in s.

(str/replace "aa bb aa" "aa" "kk")
;; => "kk bb kk"

(str/replace "aa bb aa" #"aa" "kk")
;; => "kk bb kk"

(str/replace nil #"aa" "kk")
;; => nil

replace-first

Replaces first instance of match with replacement in s.

(str/replace-first "aa bb aa" "aa" "kk")
;; => "kk bb aa"

(str/replace-first "aa bb aa" #"aa" "kk")
;; => "kk bb aa"

(str/replace-first nil #"aa" "kk")
;; => nil

surround

Surround a string with another string.

(str/surround "a" "-")
;; => "-a-"

(str/surround "a" "-^-")
;; => "-^-a-^-"

(str/surround nil "-^-")
;; => nil

unsurround

Unsurround a string surrounded by another.

(str/unsurround "-a-" "-")
;; => "a"

(str/unsurround "-^-a-^-" "-^-")
;; => "a"

(str/unsurround nil "-")
;; => nil

quote

Quote a string.

(str/quote "a")
;; => "\"a\""

(str/quote nil)
;; => nil

unquote

Unquote a string.

(str/unquote "\"a\"")
;; => "a"

(str/unquote nil)
;; => nil

slugify

Transforms string into URL slug.

(str/slugify "Un éléphant à l'orée du bois")
;; => "un-elephant-a-loree-du-bois"

(str/slugify nil)
;; => nil

strip-tags

Remove html tags from string.

(str/strip-tags "<p>just <b>some</b> text</p>")
;; => "just some text"

(str/strip-tags "<p>just <b>some</b> text</p>" ["p"])
;; => "just <b>some</b> text"

(str/strip-tags nil)
;; => nil

It also allows arbitrary replacements:

(str/strip-tags "<p>just<br>text</p>" {:br "\n"})
;; => "just\ntext"

(str/strip-tags "<p>just<br>text</p>" ["br"] {:br "\n"})
;; => "<p>just\ntext</p>"

clean

Trim and replace multiple spaces with a single space.

(str/clean "  a   b   ")
;; => "a b"

(str/clean nil)
;; => nil

strip-newlines

Takes a string and replaces newlines with a space. Multiple lines are replaced with a single space.

(str/strip-newlines "a\n\nb")
;; => "a b"

(str/strip-newlines nil)
;; => nil

parse-number

General purpose function for parse number like strings to number. It works with integers and floats.

(str/parse-number "1.4")
;; => 1

(str/parse-number "1.4" 1)
;; => 1.4

(str/parse-number "1" 2)
;; => 1

(str/parse-number "")
;; => NaN

only on clojurescript

parse-float

Returns a float value. Wraps parseFloat.

(str/parse-float "1.4")
;; => 1.4

(str/parse-float "1")
;; => 1.0

(str/parse-float nil)
;; => NaN

only on clojurescript

parse-int

Returns a number value in integer form. Wraps parseInt.

(str/parse-int "1.4")
;; => 1

(str/parse-int nil)
;; => NaN

only on clojurescript

parse-double

Returns a number value in integer form. Wraps parseInt.

(str/parse-double "1.4")
;; => 1.4

(str/parse-double nil)
;; => NaN

only on clojure

parse-long

Returns a number value in integer form. Wraps parseInt.

(str/parse-long "1.4")
;; => 1

(str/parse-long nil)
;; => NaN

only on clojure

format

Simple string interpolation.

(str/format "hello %s" "yen")
;; => "hello yen"

(str/format "hello %(name)s" {:name "yen"})
;; => "hello yen"

pad

Pads the str with characters until the total string length is equal to the passed length parameter.

By default, pads on the left with the space char.

(str/pad "1" {:length 8})
;; => "       1"

(str/pad nil {:length 8})
;; => nil

(str/pad "1" {:length 8 :padding "0"})
;; => "00000001"

(str/pad "1" {:length 8 :padding "0" :type :right})
;; => "10000000"

(str/pad "1" {:length 8 :padding "0" :type :both})
;; => "00001000"

capitalize

Converts first letter of the string to uppercase.

(str/capitalize "foo")
;; => "Foo"

(str/capitalize nil)
;; => nil

camelize

Converts a string from selector-case to camelCase.

(str/camelize "foo bar")
;; => "fooBar"

(str/camelize nil)
;; => nil

dasherize

Converts a underscored or camelized string into an dasherized one.

(str/dasherize "MozTransform")
;; => "-moz-transform"

(str/dasherize nil)
;; => nil

underscored

Converts a camelized or dasherized string into an underscored one.

(str/underscored "MozTransform")
;; => "moz_transform"

(str/underscored nil)
;; => nil

titleize

Converts a string into TitleCase.

(str/titleize "my name is epeli")
;; => "My Name Is Epeli"

(str/titleize nil)
;; => nil

classify

Converts string to camelized class name. First letter is always upper case.

(str/classify "some_class_name")
;; => "SomeClassName"

(str/classify nil)
;; => nil

humanize

Converts an underscored, camelized, or dasherized string into a humanized one.

(str/humanize "  capitalize dash-CamelCase_underscore trim  ")
;; => "Capitalize dash camel case underscore trim"

(str/humanize nil)
;; => nil

escape-regexp

Escape characters on the string that are not safe to use in a RegExp.

(str/escape-regexp "\s")
;; => "\\s"

Run tests

cuerdas has splitted implementation for clojure and clojurescript, but tests are build using speclj and cljx for execute the same tests for both implementations.

For run tests, cljx source should be compiled.

Additional note for run clojurescript tests: you should have instaled phantomjs.

Compile cljx source, and keep watching changes.

$ lein cljx auto

Run tests for clojure and keep watching changes.

$ lein spec -a

Compile clojurescript and run test on successful build.

$ lein cljsbuild auto dev

How to Contribute?

cuerdas unlike Clojure and other Clojure contrib libs, does not have many restrictions for contributions.

Pull requests are welcome!

License

cuerdas is licensed under BSD (2-Clause) license:

Copyright (c) 2014-2015, Andrey Antukh <niwi@niwi.be>

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.