# `NeoFaker.Person`
[🔗](https://github.com/muzhawir/neo_faker/blob/main/lib/neo_faker/person.ex#L1)

Functions for generating person-related information.

Provides utilities to generate random personal details including first, middle,
and last names, full names, prefixes, suffixes, ages, and genders with support
for multiple locales and sex options.

# `age`
*since 0.6.0* 

```elixir
@spec age(non_neg_integer(), non_neg_integer()) :: non_neg_integer()
```

Generates a random age as a non-negative integer between `min` and `max`, inclusive.

`min` defaults to `0` and `max` defaults to `120`.

## Examples

    iex> NeoFaker.Person.age()
    44

    iex> NeoFaker.Person.age(7, 44)
    27

    iex> NeoFaker.Person.age(18, 65)
    35

# `first_name`
*since 0.7.0* 

```elixir
@spec first_name(keyword()) :: String.t()
```

Generates a random first name.

## Options

  * `:sex` (`:unisex`, `:female`, or `:male`) - the sex of the name. Defaults to `:unisex`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Person.first_name()
    "Julia"

    iex> NeoFaker.Person.first_name(sex: :male)
    "José"

    iex> NeoFaker.Person.first_name(locale: :id_id)
    "Jaka"

# `full_name`
*since 0.7.0* 

```elixir
@spec full_name(keyword()) :: String.t()
```

Generates a random full name.

Combines a first name, an optional middle name, and a last name.

## Options

  * `:sex` (`:unisex`, `:female`, or `:male`) - the sex of the name. Defaults to `:unisex`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.
  * `:middle_name` (boolean) - whether to include a middle name. Defaults to `true`.

## Examples

    iex> NeoFaker.Person.full_name()
    "Abigail Bethany Crawford"

    iex> NeoFaker.Person.full_name(sex: :male)
    "Daniel Edward Fisher"

    iex> NeoFaker.Person.full_name(middle_name: false)
    "Gabriella Harrison"

    iex> NeoFaker.Person.full_name(sex: :female, locale: :id_id, middle_name: false)
    "Siti Nurhaliza"

# `full_name_with_title`
*since 0.6.0* 

```elixir
@spec full_name_with_title(keyword()) :: String.t()
```

Generates a random full name with optional prefix and/or suffix.

Delegates to `full_name/1` and wraps the result with the requested title parts.

## Options

  * `:sex` (`:unisex`, `:female`, or `:male`) - the sex of the name. Defaults to `:unisex`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.
  * `:middle_name` (boolean) - whether to include a middle name. Defaults to `true`.
  * `:prefix` (boolean) - when `true`, prepends a name prefix such as `"Mr."` or `"Dr."`.
    Defaults to `false`.
  * `:suffix` (boolean) - when `true`, appends a name suffix such as `"Jr."` or `"III"`.
    Defaults to `false`.

## Examples

    iex> NeoFaker.Person.full_name_with_title(prefix: true)
    "Dr. Abigail Bethany Crawford"

    iex> NeoFaker.Person.full_name_with_title(suffix: true)
    "Daniel Edward Fisher Jr."

    iex> NeoFaker.Person.full_name_with_title(prefix: true, suffix: true, middle_name: false)
    "Mr. John Smith III"

# `gender`
*since 0.15.0* 

```elixir
@spec gender(keyword()) :: String.t()
```

Generates a random gender value.

## Options

  * `:format` (`:binary`, `:short_binary`, `:non_binary`, or `:all`) - which gender
    representation to return. Defaults to `:binary`.
    * `:binary` - the full binary gender, e.g. `"Male"` or `"Female"`.
    * `:short_binary` - the abbreviated binary gender, e.g. `"M"` or `"F"`.
    * `:non_binary` - a non-binary gender identity string, e.g. `"Non-binary"`.
    * `:all` - the binary and non-binary identities combined, e.g. `"Female"` or
      `"Genderfluid"`. The abbreviated `:short_binary` codes are left out, since they are
      just shorthand for the binary values.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Person.gender()
    "Male"

    iex> NeoFaker.Person.gender(format: :short_binary)
    "M"

    iex> NeoFaker.Person.gender(format: :non_binary)
    "Non-binary"

    iex> NeoFaker.Person.gender(format: :all)
    "Genderfluid"

    iex> NeoFaker.Person.gender(locale: :id_id)
    "Perempuan"

# `last_name`
*since 0.7.0* 

```elixir
@spec last_name(keyword()) :: String.t()
```

Generates a random last name.

## Options

  * `:sex` (`:unisex`, `:female`, or `:male`) - the sex of the name. Defaults to `:unisex`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Person.last_name()
    "Smith"

    iex> NeoFaker.Person.last_name(sex: :male)
    "Johnson"

    iex> NeoFaker.Person.last_name(locale: :id_id)
    "Wijaya"

# `middle_name`
*since 0.7.0* 

```elixir
@spec middle_name(keyword()) :: String.t()
```

Generates a random middle name.

## Options

  * `:sex` (`:unisex`, `:female`, or `:male`) - the sex of the name. Defaults to `:unisex`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Person.middle_name()
    "Anne"

    iex> NeoFaker.Person.middle_name(sex: :male)
    "James"

    iex> NeoFaker.Person.middle_name(locale: :id_id)
    "Budi"

# `prefix`
*since 0.7.0* 

```elixir
@spec prefix(keyword()) :: String.t()
```

Generates a random name prefix such as `"Mr."`, `"Ms."`, or `"Dr."`.

## Options

  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Person.prefix()
    "Mr."

    iex> NeoFaker.Person.prefix(locale: :id_id)
    "Tn."

# `suffix`
*since 0.7.0* 

```elixir
@spec suffix(keyword()) :: String.t()
```

Generates a random name suffix such as `"Jr."`, `"Sr."`, or `"III"`.

## Options

  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

    iex> NeoFaker.Person.suffix()
    "Jr."

    iex> NeoFaker.Person.suffix(locale: :id_id)
    "S.Kom"

    iex> NeoFaker.Person.suffix(locale: :en_us)
    "III"

---

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