% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/na-if.R
\name{na_if}
\alias{na_if}
\title{Convert values to \code{NA}}
\usage{
na_if(x, y)
}
\arguments{
\item{x}{Vector to modify}

\item{y}{Value or vector to compare against. When \code{x} and \code{y} are equal, the
value in \code{x} will be replaced with \code{NA}.

\code{y} is \link[vctrs:theory-faq-coercion]{cast} to the type of \code{x} before
comparison.

\code{y} is \link[vctrs:theory-faq-recycling]{recycled} to the size of \code{x} before
comparison. This means that \code{y} can be a vector with the same size as \code{x},
but most of the time this will be a single value.}
}
\value{
A modified version of \code{x} that replaces any values that
are equal to \code{y} with \code{NA}.
}
\description{
This is a translation of the SQL command \code{NULLIF}. It is useful if you want
to convert an annoying value to \code{NA}.
}
\examples{
# `na_if()` is useful for replacing a single problematic value with `NA`
na_if(c(-99, 1, 4, 3, -99, 5), -99)
na_if(c("abc", "def", "", "ghi"), "")

# You can use it to standardize `NaN`s to `NA`
na_if(c(1, NaN, NA, 2, NaN), NaN)

# Because `na_if()` is an R translation of SQL's `NULLIF` command,
# it compares `x` and `y` element by element. Where `x` and `y` are
# equal, the value in `x` is replaced with an `NA`.
na_if(
  x = c(1, 2, 5, 5, 6),
  y = c(0, 2, 3, 5, 4)
)

# If you have multiple problematic values that you'd like to replace with
# `NA`, then `replace_values()` is a better choice than `na_if()`
x <- c(-99, 1, 4, 0, -99, 5, -1, 0, 5)
replace_values(x, c(0, -1, -99) ~ NA)

# You'd have to nest `na_if()`s to achieve this
try(na_if(x, c(0, -1, -99)))
na_if(na_if(na_if(x, 0), -1), -99)

# If you'd like to replace values that match a logical condition with `NA`,
# use `replace_when()`
replace_when(x, x < 0 ~ NA)

# If you'd like to replace `NA` with some other value, use `replace_values()`
x <- c(NA, 5, 2, NA, 0, 3)
replace_values(x, NA ~ 0)

# `na_if()` is particularly useful inside `mutate()`
starwars |>
  select(name, eye_color) |>
  mutate(eye_color = na_if(eye_color, "unknown"))

# `na_if()` can also be used with `mutate()` and `across()`
# to alter multiple columns
starwars |>
   mutate(across(where(is.character), ~na_if(., "unknown")))
}
\seealso{
\itemize{
\item \code{\link[=coalesce]{coalesce()}} to replace \code{NA}s with the first non-missing value.
\item \code{\link[=replace_values]{replace_values()}} for making arbitrary replacements by value.
\item \code{\link[=replace_when]{replace_when()}} for making arbitrary replacements using logical
conditions.
}
}
