From 27a21becc1f7c45a7f2082a557563467f0ab7419 Mon Sep 17 00:00:00 2001
From: hadley <h.wickham@gmail.com>
Date: Thu, 29 Oct 2015 16:12:30 -0500
Subject: [PATCH] Implement add_row.

Fixes #1021
---
 NAMESPACE      |  1 +
 R/dataframe.R  | 44 ++++++++++++++++++++++++++++++++++++++++++++
 man/add_row.Rd | 42 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)
 create mode 100644 man/add_row.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 0d3438d83e..3d7688ad5f 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -288,6 +288,7 @@ S3method(unique,sql)
 S3method(update,tbl_sql)
 export("%>%")
 export(.datatable.aware)
+export(add_row)
 export(add_rownames)
 export(anti_join)
 export(arrange)
diff --git a/R/dataframe.R b/R/dataframe.R
index 1bf4671120..5c5a63c195 100644
--- a/R/dataframe.R
+++ b/R/dataframe.R
@@ -162,6 +162,50 @@ add_rownames <- function(df, var = "rowname") {
   bind_cols(rn, df)
 }
 
+#' Add a row to a data frame
+#'
+#' This is a convenient way to add a single row of data to an existing data
+#' frame. See \code{\link{frame_data}} for an easy way to create an complete
+#' data frame row-by-row.
+#'
+#' @param .data Data frame to append to.
+#' @param ... Name-value pairs. If you don't supply the name of a variable,
+#'   it'll be given the value \code{NA}.
+#' @examples
+#' # add_row ---------------------------------
+#' df <- data_frame(x = 1:3, y = 3:1)
+#'
+#' df %>%
+#'   add_row(x = 4, y = 0)
+#'
+#' # You can supply vectors, to add multiple rows (this isn't
+#' # recommended because it's a bit hard to read)
+#' df %>%
+#'   add_row(x = 4:5, y = 0:-1)
+#'
+#' # Absent variables get missing values
+#' df %>%
+#'   add_row(x = 4)
+#'
+#' # You can't create new variables
+#' \dontrun{
+#' df %>%
+#'   add_row(z = 10)
+#' }
+#' @export
+add_row <- function(.data, ...) {
+  df <- data_frame(...)
+
+  extra_vars <- setdiff(names(df), names(.data))
+  if (length(extra_vars) > 0) {
+    stop(
+      "This row would add new variables: ", paste0(extra_vars, collapse = ", "),
+      call. = FALSE
+    )
+  }
+
+  bind_rows(.data, data_frame(...))
+}
 
 # Validity checks --------------------------------------------------------------
 
diff --git a/man/add_row.Rd b/man/add_row.Rd
new file mode 100644
index 0000000000..9d8cb2e8d6
--- /dev/null
+++ b/man/add_row.Rd
@@ -0,0 +1,42 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/dataframe.R
+\name{add_row}
+\alias{add_row}
+\title{Add a row to a data frame}
+\usage{
+add_row(.data, ...)
+}
+\arguments{
+\item{.data}{Data frame to append to.}
+
+\item{...}{Name-value pairs. If you don't supply the name of a variable,
+it'll be given the value \code{NA}.}
+}
+\description{
+This is a convenient way to add a single row of data to an existing data
+frame. See \code{\link{frame_data}} for an easy way to create an complete
+data frame row-by-row.
+}
+\examples{
+# add_row ---------------------------------
+df <- data_frame(x = 1:3, y = 3:1)
+
+df \%>\%
+  add_row(x = 4, y = 0)
+
+# You can supply vectors, to add multiple rows (this isn't
+# recommended because it's a bit hard to read)
+df \%>\%
+  add_row(x = 4:5, y = 0:-1)
+
+# Absent variables get missing values
+df \%>\%
+  add_row(x = 4)
+
+# You can't create new variables
+\dontrun{
+df \%>\%
+  add_row(z = 10)
+}
+}
+