@spec append_unless_blank(binary() | nil, binary() | nil) :: binary()

Appends suffix to string unless string is blank according to Moar.Term.blank?/1.

iex> Moar.String.append_unless_blank("foo", "-bar")
"foo-bar"

iex> Moar.String.append_unless_blank("", "-bar")
""

iex> Moar.String.append_unless_blank(nil, "-bar")
nil

@spec compare(binary(), binary(), (binary() -> binary()) | [(binary() -> binary())]) ::
  :lt | :eq | :gt

Compares two strings, returning :lt, :eq, or :gt depending on whether the first arg is less than, equal to, or greater than the second arg. Accepts one or more functions that transform the inputs before comparison.

See Moar.String.compare?/2 for a version that returns true or false.

iex> Moar.String.compare("foo", "FOO")
:gt

iex> Moar.String.compare("foo", "FOO", &String.downcase/1)
:eq

iex> Moar.String.compare("foo bar", " FOO    bar ", [&String.downcase/1, &Moar.String.squish/1])
:eq

@spec compare?(binary(), binary(), (binary() -> binary()) | [(binary() -> binary())]) ::
  boolean()

Compares two strings, returning true if the first arg is less than or equal to the second arg, or false if the first arg is greater than the second arg. Accepts one or more functions that transform the inputs before comparison. Useful for sorter functions like what is passed into Enum.sort/2.

See Moar.String.compare/2 for a version that returns :lt, :eq, or :gt.

iex> Moar.String.compare?("foo", "FOO")
false

iex> Moar.String.compare?("foo", "FOO", &String.downcase/1)
true

iex> Moar.String.compare?("foo bar", " FOO    bar ", [&String.downcase/1, &Moar.String.squish/1])
true

@spec count_leading_spaces(binary()) :: non_neg_integer()

Returns the number of leading spaces. Only considers "plain" spaces, not all unicode whitespace.

iex> Moar.String.count_leading_spaces("  foo")
2

@spec dasherize(String.Chars.t() | [String.Chars.t()]) :: binary()

Dasherizes term. A shortcut to slug(term, "-").

See docs for slug/2.

iex> Moar.String.dasherize("foo bar")
"foo-bar"

@spec inner_truncate(binary(), integer(), binary()) :: binary()

Truncate s to max_length by replacing the middle of the string with replacement, which defaults to the single unicode character ….

Note that the final length of the string will be max_length plus the length of replacement.

iex> Moar.String.inner_truncate("abcdefghijklmnopqrstuvwxyz", 10)
"abcde…vwxyz"

iex> Moar.String.inner_truncate("abcdefghijklmnopqrstuvwxyz", 10, "<==>")
"abcde<==>vwxyz"

@spec lorem(non_neg_integer()) :: String.t()

Creates a lorem ipsum string of length character_count.

@spec pluralize(number(), binary(), binary() | function()) :: binary()

Pluralizes a string.

When count is -1 or 1, returns the second argument (the singular string).

Otherwise, returns the third argument (the pluralized string), or if the third argument is a function, calls the function with the singular string as an argument.

iex> Moar.String.pluralize(1, "fish", "fishies")
"fish"

iex> Moar.String.pluralize(2, "fish", "fishies")
"fishies"

iex> Moar.String.pluralize(2, "fish", fn singular -> singular <> "ies" end)
"fishies"

iex> Moar.String.pluralize(2, "fish", &(&1 <> "ies"))
"fishies"

@spec remove_marked_whitespace(binary()) :: binary()

Removes all whitespace following a backspace+v escape code.

Especially useful in test assertions where only some of the whitespace matters.

iex> Moar.String.remove_marked_whitespace("one two three	   four five")
"one two threefour five"

@spec secure_compare(binary(), binary()) :: boolean()

Compares the two binaries in constant-time to avoid timing attacks. See: http://codahale.com/a-lesson-in-timing-attacks/.

iex> Moar.String.secure_compare("foo", "bar")
false

@spec slug(String.Chars.t() | [String.Chars.t()], binary()) :: binary()

Creates slugs like foo-bar-123 or foo_bar from various input types.

Converts strings, atoms, and anything else that implements String.Chars, plus lists of those things, to a single string after removing non-alphanumeric characters, and then joins them with joiner. Existing occurrences of joiner are kept, including leading and trailing ones.

dasherize/1 and underscore/1 are shortcuts that specify a joiner.

iex> Moar.String.slug("foo bar", "_")
"foo_bar"

iex> Moar.String.slug("foo bar", "+")
"foo+bar"

iex> Moar.String.slug(["foo", "bar"], "+")
"foo+bar"

iex> Moar.String.slug("_foo bar", "_")
"_foo_bar"

iex> ["foo", "FOO", :foo] |> Enum.map(&Moar.String.slug(&1, "-"))
["foo", "foo", "foo"]

iex> ["foo-bar", "foo_bar", :foo_bar, " fooBar ", "  ?foo ! bar  "] |> Enum.map(&Moar.String.slug(&1, "-"))
["foo-bar", "foo-bar", "foo-bar", "foo-bar", "foo-bar"]

@spec squish(binary()) :: binary()

Trims spaces from the beginning and end of a string, and replaces consecutive whitespace characters with a single space.

iex> Moar.String.squish("  foo   bar  	baz ")
"foo bar baz"

@spec surround(binary(), binary()) :: binary()

Adds surrounder to the beginning and end of s.

iex> Moar.String.surround("Hello", "**")
"**Hello**"

@spec surround(binary(), binary(), binary()) :: binary()

Adds prefix to the beginning of s and suffix to the end.

iex> Moar.String.surround("Hello", "“", "”")
"“Hello”"

@spec to_case(binary(), string_case()) :: binary()

Change the case of a string.

iex> Moar.String.to_case("text_with_case", :camel_case)
"TextWithCase"
iex> Moar.String.to_case("textWithCase", :camel_case)
"TextWithCase"
iex> Moar.String.to_case("some random text", :camel_case)
"SomeRandomText"

iex> Moar.String.to_case("text_with_case", :lower_camel_case)
"textWithCase"
iex> Moar.String.to_case("textWithCase", :lower_camel_case)
"textWithCase"
iex> Moar.String.to_case("some random text", :lower_camel_case)
"someRandomText"

iex> Moar.String.to_case("text_with_case", :snake_case)
"text_with_case"
iex> Moar.String.to_case("textWithCase", :snake_case)
"text_with_case"
iex> Moar.String.to_case("some random text", :snake_case)
"some_random_text"

@spec to_integer(nil | binary()) :: integer()

Converts a string to an integer. Returns nil if the argument is nil or empty string. Returns the argument without complaint if it is already an integer.

iex> Moar.String.to_integer("12,345")
12_345

iex> Moar.String.to_integer("")
nil

iex> Moar.String.to_integer(12_345)
12_345

@spec to_integer(binary(), :lenient | [{:default, binary()}]) :: integer()

Like to_integer/1 but with options:

• :lenient option removes non-digit characters first
• default: option specifies a default in case s is nil

iex> Moar.String.to_integer("USD$25", :lenient)
25

iex> Moar.String.to_integer(nil, default: 0)
0

@spec trim(nil | binary()) :: nil | binary()

Like String.trim/1 but returns nil if the argument is nil.

Truncates s at the last instance of at, causing the string to be at most limit characters.

iex> Moar.String.truncate_at("I like apples. I like bananas. I like cherries.", ".", 35)
"I like apples. I like bananas."

@spec underscore(String.Chars.t() | [String.Chars.t()]) :: binary()

Underscores term. A shortcut to slug(term, "_").

See docs for slug/2.

iex> Moar.String.underscore("foo bar")
"foo_bar"

@spec unindent(binary()) :: binary()

Unindents a string by finding the smallest indentation of the string, and removing that many spaces from each line. Only considers "plain" spaces, not all unicode whitespace.

iex> """
...>      ant
...>    bat
...>      cat
...>        dog
...> """ |> Moar.String.unindent()
"  ant
bat
  cat
    dog
"

@spec unindent(binary(), non_neg_integer()) :: binary()

Unindents a string by count spaces. Only considers "plain" spaces, not all unicode whitespace.

iex> """
...> foo
...>   bar
...>     baz
...> """ |> Moar.String.unindent(2)
"foo
bar
  baz
"