> ## Documentation Index
> Fetch the complete documentation index at: https://validity-kt.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Strings

> Length, content, characters and text formats of a String.

The constraints of a `String` value. Length counts characters as Kotlin does (`String.length`), and the byte rules
count the bytes of an encoding, UTF-8 by default. The rules that compare with text you give take `ignoreCase`, `false`
by default.

> [!NOTE]
>
> A `null` argument checks nothing. A rule that reads a value that may be missing, such as `max(customer.limit)`,
> never fails because of it: `required` on that value reports it once.

```kotlin MemberProfile.kt theme={null}
data class MemberProfile(
    val handle: String?,
    val displayName: String?,
    val password: String?,
    val bio: String? = null
) : Validatable {
    override fun validation() = validation {
        ::handle required {
            lengthBetween(min = 3, max = 30)
            lowercase()
            slug()
        }
        ::displayName required {
            notBlank()
            trimmed()
        }
        ::password required {
            minLength(12)
            containsUppercase()
            containsDigit()
            containsSymbol()
        }
        ::bio ifPresent { maxBytes(500) }
    }
}
```

| Constraint | Checks |
| - | - |
| [`minLength`](#minlength) | Has at least `min` characters. |
| [`maxLength`](#maxlength) | Has at most `max` characters. |
| [`length`](#length) | Has exactly `length` characters. |
| [`lengthBetween`](#lengthbetween) | Has between `min` and `max` characters, both included. |
| [`minBytes`](#minbytes) | Takes at least `min` bytes when encoded with `charset`. |
| [`maxBytes`](#maxbytes) | Takes at most `max` bytes when encoded with `charset`. |
| [`notEmpty`](#notempty) | Has at least one character. |
| [`empty`](#empty) | Has no characters. |
| [`notBlank`](#notblank) | Has at least one character that is not whitespace. |
| [`blank`](#blank) | Is empty or has only whitespace. |
| [`trimmed`](#trimmed) | Does not start or end with whitespace. |
| [`equalTo`](#equalto) | Is equal to `other`, ignoring case when `ignoreCase` is `true`. |
| [`oneOf`](#oneof) | Is one of `values`, ignoring case when `ignoreCase` is `true`. |
| [`enum`](#enum) | Is the name of an entry of the enum `E`. |
| [`contains`](#contains) | Contains `text`. |
| [`notContains`](#notcontains) | Does not contain `text`. |
| [`startsWith`](#startswith) | Starts with `prefix`. |
| [`notStartsWith`](#notstartswith) | Does not start with `prefix`. |
| [`endsWith`](#endswith) | Ends with `suffix`. |
| [`notEndsWith`](#notendswith) | Does not end with `suffix`. |
| [`matches`](#matches) | Of the string matches `regex`. |
| [`notMatches`](#notmatches) | Of the string does not match `regex`. |
| [`uppercase`](#uppercase) | Has no lowercase letters. |
| [`lowercase`](#lowercase) | Has no uppercase letters. |
| [`letters`](#letters) | Is not empty and has only letters, in any script. |
| [`digits`](#digits) | Is not empty and has only the digits `0` to `9`. |
| [`lettersOrDigits`](#lettersordigits) | Is not empty and has only letters, in any script, and the digits `0` to `9`. |
| [`ascii`](#ascii) | Is not empty and has only ASCII characters. |
| [`containsOnly`](#containsonly) | Is not empty and has only characters from `characters`. |
| [`containsUppercase`](#containsuppercase) | Has at least one uppercase letter. |
| [`containsLowercase`](#containslowercase) | Has at least one lowercase letter. |
| [`containsDigit`](#containsdigit) | Has at least one of the digits `0` to `9`. |
| [`containsSymbol`](#containssymbol) | Has at least one character that is not a letter, a digit or whitespace. |
| [`normalized`](#normalized) | Is already in the Unicode normalization `form`. |
| [`numeric`](#numeric) | Is a decimal number, such as `42`, `-7` or `+3.14`. |
| [`integer`](#integer) | Is a whole number, such as `42`, `-7` or `+3`. |
| [`boolean`](#boolean) | Is `true` or `false`, in lowercase. |

## Length and bytes

### `minLength`

`minLength(min)` on `String`

Checks that the string has at least `min` characters.

**Code** `minLength`· **Message** `must have at least {min} characters` · **Change it** `minLength = "…"`

### `maxLength`

`maxLength(max)` on `String`

Checks that the string has at most `max` characters.

**Code** `maxLength`· **Message** `must have at most {max} characters` · **Change it** `maxLength = "…"`

### `length`

`length(length)` on `String`

Checks that the string has exactly `length` characters.

**Code** `length`· **Message** `must have exactly {length} characters` · **Change it** `length = "…"`

### `lengthBetween`

`lengthBetween(min, max)` on `String`

Checks that the string has between `min` and `max` characters, both included.

**Code** `lengthBetween`· **Message** `must have between {min} and {max} characters` · **Change it** `lengthBetween = "…"`

### `minBytes`

`minBytes(min, charset)` on `String`

Checks that the string takes at least `min` bytes when encoded with `charset`.

**Code** `minBytes`· **Message** `must have at least {min} bytes` · **Change it** `minBytes = "…"`

### `maxBytes`

`maxBytes(max, charset)` on `String`

Checks that the string takes at most `max` bytes when encoded with `charset`.

Use it for columns and protocols that limit bytes, not characters: `"é"` is one character and two UTF-8 bytes.

**Code** `maxBytes`· **Message** `must have at most {max} bytes` · **Change it** `maxBytes = "…"`

## Empty and blank

### `notEmpty`

`notEmpty()` on `String`

Checks that the string has at least one character.

A string of spaces passes. Use `notBlank` to refuse it.

**Code** `notEmpty`· **Message** `must not be empty` · **Change it** `notEmpty = "…"`

### `empty`

`empty()` on `String`

Checks that the string has no characters.

**Code** `empty`· **Message** `must be empty` · **Change it** `empty = "…"`

### `notBlank`

`notBlank()` on `String`

Checks that the string has at least one character that is not whitespace.

**Code** `notBlank`· **Message** `must not be blank` · **Change it** `notBlank = "…"`

### `blank`

`blank()` on `String`

Checks that the string is empty or has only whitespace.

**Code** `blank`· **Message** `must be blank` · **Change it** `blank = "…"`

### `trimmed`

`trimmed()` on `String`

Checks that the string does not start or end with whitespace.

**Code** `trimmed`· **Message** `must not start or end with whitespace` · **Change it** `trimmed = "…"`

## Comparing with text

### `equalTo`

`equalTo(other, ignoreCase)` on `String`

Checks that the string is equal to `other`, ignoring case when `ignoreCase` is `true`.

**Code** `equalTo`· **Message** `must be equal to {other}` · **Change it** `equalTo = "…"`

### `oneOf`

`oneOf(values, ignoreCase)` on `String`

Checks that the string is one of `values`, ignoring case when `ignoreCase` is `true`.

**Code** `oneOf`· **Message** `must be one of {values}` · **Change it** `oneOf = "…"`

### `enum`

`enum<E>(ignoreCase)` on `String`

Checks that the string is the name of an entry of the enum `E`.

**Code** `enum`· **Message** `must be one of {values}` · **Change it** `enum = "…"`

### `contains`

`contains(text, ignoreCase)` on `String`

Checks that the string contains `text`.

**Code** `contains`· **Message** `must contain {text}` · **Change it** `contains = "…"`

### `notContains`

`notContains(text, ignoreCase)` on `String`

Checks that the string does not contain `text`.

**Code** `notContains`· **Message** `must not contain {text}` · **Change it** `notContains = "…"`

### `startsWith`

`startsWith(prefix, ignoreCase)` on `String`

Checks that the string starts with `prefix`.

**Code** `startsWith`· **Message** `must start with {prefix}` · **Change it** `startsWith = "…"`

### `notStartsWith`

`notStartsWith(prefix, ignoreCase)` on `String`

Checks that the string does not start with `prefix`.

**Code** `notStartsWith`· **Message** `must not start with {prefix}` · **Change it** `notStartsWith = "…"`

### `endsWith`

`endsWith(suffix, ignoreCase)` on `String`

Checks that the string ends with `suffix`.

**Code** `endsWith`· **Message** `must end with {suffix}` · **Change it** `endsWith = "…"`

### `notEndsWith`

`notEndsWith(suffix, ignoreCase)` on `String`

Checks that the string does not end with `suffix`.

**Code** `notEndsWith`· **Message** `must not end with {suffix}` · **Change it** `notEndsWith = "…"`

### `matches`

`matches(regex)` on `String`

Checks that the whole of the string matches `regex`.

**Code** `matches`· **Message** `must match {regex}` · **Change it** `matches = "…"`

### `notMatches`

`notMatches(regex)` on `String`

Checks that the whole of the string does not match `regex`.

A string that only contains a match passes, since the whole string is what is matched.

**Code** `notMatches`· **Message** `must not match {regex}` · **Change it** `notMatches = "…"`

## Characters

### `uppercase`

`uppercase()` on `String`

Checks that the string has no lowercase letters.

Digits, symbols and the empty string pass.

**Code** `uppercase`· **Message** `must be uppercase` · **Change it** `uppercase = "…"`

### `lowercase`

`lowercase()` on `String`

Checks that the string has no uppercase letters.

As with `uppercase`, digits, symbols and the empty string pass.

**Code** `lowercase`· **Message** `must be lowercase` · **Change it** `lowercase = "…"`

### `letters`

`letters()` on `String`

Checks that the string is not empty and has only letters, in any script.

**Code** `letters`· **Message** `must contain only letters` · **Change it** `letters = "…"`

### `digits`

`digits()` on `String`

Checks that the string is not empty and has only the digits `0` to `9`.

**Code** `digits`· **Message** `must contain only digits` · **Change it** `digits = "…"`

### `lettersOrDigits`

`lettersOrDigits()` on `String`

Checks that the string is not empty and has only letters, in any script, and the digits `0` to `9`.

**Code** `lettersOrDigits`· **Message** `must contain only letters or digits` · **Change it** `lettersOrDigits = "…"`

### `ascii`

`ascii()` on `String`

Checks that the string is not empty and has only ASCII characters.

**Code** `ascii`· **Message** `must contain only ASCII characters` · **Change it** `ascii = "…"`

### `containsOnly`

`containsOnly(characters)` on `String`

Checks that the string is not empty and has only characters from `characters`.

**Code** `containsOnly`· **Message** `must contain only the characters {characters}` · **Change it** `containsOnly = "…"`

### `containsUppercase`

`containsUppercase()` on `String`

Checks that the string has at least one uppercase letter.

**Code** `containsUppercase`· **Message** `must contain an uppercase letter` · **Change it** `containsUppercase = "…"`

### `containsLowercase`

`containsLowercase()` on `String`

Checks that the string has at least one lowercase letter.

**Code** `containsLowercase`· **Message** `must contain a lowercase letter` · **Change it** `containsLowercase = "…"`

### `containsDigit`

`containsDigit()` on `String`

Checks that the string has at least one of the digits `0` to `9`.

**Code** `containsDigit`· **Message** `must contain a digit` · **Change it** `containsDigit = "…"`

### `containsSymbol`

`containsSymbol()` on `String`

Checks that the string has at least one character that is not a letter, a digit or whitespace.

**Code** `containsSymbol`· **Message** `must contain a symbol` · **Change it** `containsSymbol = "…"`

### `normalized`

`normalized(form)` on `String`

Checks that the string is already in the Unicode normalization `form`.

**Code** `normalized`· **Message** `must be in Unicode {form} form` · **Change it** `normalized = "…"`

## Text that carries a value

### `numeric`

`numeric()` on `String`

Checks that the string is a decimal number, such as `42`, `-7` or `+3.14`.

There is no exponent and no thousands separator.

**Code** `numeric`· **Message** `must be numeric` · **Change it** `numeric = "…"`

### `integer`

`integer()` on `String`

Checks that the string is a whole number, such as `42`, `-7` or `+3`.

**Code** `integer`· **Message** `must be an integer` · **Change it** `integer = "…"`

### `boolean`

`boolean()` on `String`

Checks that the string is `true` or `false`, in lowercase.

**Code** `boolean`· **Message** `must be true or false` · **Change it** `boolean = "…"`

> [!TIP]
>
> More string formats have pages of their own: [internet](https://validity-kt.dev/constraints/internet.md) (`email`, `url`, `ipv4`),
> [identifiers](https://validity-kt.dev/constraints/identifiers.md) (`uuid`, `isbn`), [encodings](https://validity-kt.dev/constraints/encodings.md) (`base64`, `json`),
> [finance](https://validity-kt.dev/constraints/finance.md) (`iban`, `creditCard`), [dates](https://validity-kt.dev/constraints/date-formats.md) and
> [countries](https://validity-kt.dev/constraints/countries.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.