# -------------------------------------------------------------------------------------------------------------------------  #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #           File Name              :  joins.r                                                                                #
  #           Last Updated Funclist  :  08 Feb 2015,  5:12 AM (Sunday)                                                         #
  #                                                                                                                            #
  #           Author Name            :  Rick Saporta                                                                           #
  #           Author Email           :  RickSaporta@gmail.com                                                                  #
  #           Author URL             :  www.github.com/rsaporta                                                                #
  #                                                                                                                            #
  #           Packages Called        :  NA                                                                                     #
  #           Packages Used via NS   :  NA                                                                                     #
  #                                                                                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #   uniqueJoin         ( x, y, preserve.ordering=c("left", "right") )                                                        #
  #   rightJoin          ( x, y )                                                                                              #
  #   leftJoin           ( x, y )                                                                                              #
  #                                                                                                                            #
  #                                                                                                                            #
  #                                                     <END FUNCS>                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  # -------------------------------------------------------------------------------------------------------------------------  #

  ## NOTE TO SELF: "rightjoin no longer sends unique values.\nHINT: use uniqueOutterJoin")


uniqueJoin <- function(x, y, preserve.ordering=c("left", "right")) {
## This is the equivalent of calling unique(c(x, y)) but
##  with the added bonus that ordering of the shared-elements can be 
##  either according to x or to y
  preserve.ordering <- match.arg(preserve.ordering)
  if (preserve.ordering == "left") {
    x <- unique(x)
    y <- setdiff(y, x)
  } else {
    y <- unique(y)
    x <- setdiff(x, y)
  }
  return(c(x, y))
}

rightJoin <- function(x, y) {
## aka right-outter join
  c(x[x %in% y], y)
}

leftJoin <- function(x, y) {
## aka left-outter join

  c(x, y[y %in% x])
}


## EXAMPLES

if (FALSE) {

  left  <- c("A", "B",       "D")
  right <- c("A",      "C",  "D")

  rightJoin(left, right)
  # [1] "A" "D" "A" "C" "D"

  leftJoin(left, right)
  # [1] "A" "B" "D" "A" "D"

  uniqueOutterJoin(left, right, preserve="left")
  # [1] "B" "A" "C" "D"

  uniqueOutterJoin(left, right, preserve="right")
  # [1] "A" "B" "D" "C"

}