# `Machete.StringMatcher`
[🔗](https://github.com/mtrudel/machete/blob/main/lib/machete/matchers/string_matcher.ex#L1)

Defines a matcher that matches string values

# `opts`

```elixir
@type opts() :: [
  empty: boolean(),
  length: non_neg_integer(),
  min: non_neg_integer(),
  max: non_neg_integer(),
  matches: Regex.t(),
  alphabetic: boolean(),
  lowercase: boolean(),
  uppercase: boolean(),
  alphanumeric: boolean(),
  numeric: boolean(),
  hexdecimal: boolean(),
  whitespace: boolean(),
  starts_with: String.t(),
  ends_with: String.t()
]
```

Describes the arguments that can be passed to this matcher

# `t`

```elixir
@opaque t()
```

Describes an instance of this matcher

# `string`

```elixir
@spec string(opts()) :: t()
```

Matches against string values

Takes the following arguments:

* `empty`: When `true`, requires the matched string be empty. When false, requires the matched
  string to be non-empty
* `length`: Requires the matched string to be exactly the specified length
* `min`: Requires the matched string to be greater than or equal to the specified length
* `max`: Requires the matched string to be less than or equal to the specified length
* `matches`: Requires the matched string to match the specified regex
* `alphabetic`: When `true`, requires the matched string to consist of only alphabetic characters
* `lowercase`: When `true`, requires the matched string to consist of only lowercase characters
* `uppercase`: When `true`, requires the matched string to consist of only uppercase characters
* `alphanumeric`: When `true`, requires the matched string to consist of only alphanumeric characters
* `numeric`: When `true`, requires the matched string to consist of only numeric characters
* `hexadecimal`: When `true`, requires the matched string to consist of only hexadecimal characters
* `whitespace`: When `true`, requires the string to contain whitespace (possibly in addition to
  other characters). When `false`, requires the matched string to not contain any whitespace
* `starts_with`: Requires the matched string to start with the given prefix
* `ends_with`: Requires the matched string to end with the given suffix

Examples:

    iex> assert "" ~> string()
    true

    iex> assert "abc" ~> string(length: 3)
    true

    iex> assert "abc" ~> string(min: 3)
    true

    iex> assert "abc" ~> string(max: 3)
    true

    iex> assert "" ~> string(empty: true)
    true

    iex> assert "abc" ~> string(empty: false)
    true

    iex> assert "abc" ~> string(matches: ~r/abc/)
    true

    iex> assert "abc" ~> string(alphabetic: true)
    true

    iex> assert "123" ~> string(alphabetic: false)
    true

    iex> assert "abc" ~> string(lowercase: true)
    true

    iex> assert "ABC" ~> string(lowercase: false)
    true

    iex> assert "ABC" ~> string(uppercase: true)
    true

    iex> assert "abc" ~> string(uppercase: false)
    true

    iex> assert "abc123" ~> string(alphanumeric: true)
    true

    iex> assert "$" ~> string(alphanumeric: false)
    true

    iex> assert "123" ~> string(numeric: true)
    true

    iex> assert "abc" ~> string(numeric: false)
    true

    iex> assert "deadbeef0123" ~> string(hexadecimal: true)
    true

    iex> assert "ghi" ~> string(hexadecimal: false)
    true

    iex> assert "abc def" ~> string(whitespace: true)
    true

    iex> assert "abcdef" ~> string(whitespace: false)
    true

    iex> assert "abc" ~> string(starts_with: "ab")
    true

    iex> assert "abc" ~> string(ends_with: "bc")
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*