(#20684) Add array comparison functions, difference, intersection and union.

Included is code, tests and documentation for the difference, intersection
and union functions for comparing arrays.

Author: Alex Cline

README.markdown

@@ -195,6 +195,18 @@ Would return: ['a','c']
 
 - *Type*: rvalue
 
+difference
+----------
+This function returns the difference between two arrays.
+The returned array is a copy of the original array, removing any items that
+also appear in the second array.
+
+*Examples:*
+
+    difference(["a","b","c"],["b","c","d"])
+
+Would return: ["a"]
+
 dirname
 -------
 Returns the `dirname` of a path.
@@ -416,6 +428,16 @@ Would return: {'a'=>1,'b'=>2,'c'=>3}
 
 - *Type*: rvalue
 
+intersection
+-----------
+This function returns an array an intersection of two.
+
+*Examples:*
+
+    intersection(["a","b","c"],["b","c","d"])
+
+Would return: ["b","c"]
+
 is_array
 --------
 Returns true if the variable passed to this function is an array.
@@ -868,6 +890,17 @@ Returns the type when passed a variable. Type can be one of:
 
 - *Type*: rvalue
 
+union
+-----
+This function returns a union of two arrays.
+
+*Examples:*
+
+    union(["a","b","c"],["b","c","d"])
+
+Would return: ["a","b","c","d"]
+
+
 unique
 ------
 This function will remove duplicates from strings and arrays.

lib/puppet/parser/functions/difference.rb

@@ -0,0 +1,36 @@
+#
+# difference.rb
+#
+
+module Puppet::Parser::Functions
+  newfunction(:difference, :type => :rvalue, :doc => <<-EOS
+This function returns the difference between two arrays.
+The returned array is a copy of the original array, removing any items that
+also appear in the second array.
+
+*Examples:*
+
+    difference(["a","b","c"],["b","c","d"])
+
+Would return: ["a"]
+    EOS
+  ) do |arguments|
+
+    # Two arguments are required
+    raise(Puppet::ParseError, "difference(): Wrong number of arguments " +
+      "given (#{arguments.size} for 2)") if arguments.size != 2
+
+    first = arguments[0]
+    second = arguments[1]
+
+    unless first.is_a?(Array) && second.is_a?(Array)
+      raise(Puppet::ParseError, 'difference(): Requires 2 arrays')
+    end
+
+    result = first - second
+
+    return result
+  end
+end
+
+# vim: set ts=2 sw=2 et :

lib/puppet/parser/functions/intersection.rb

@@ -0,0 +1,34 @@
+#
+# intersection.rb
+#
+
+module Puppet::Parser::Functions
+  newfunction(:intersection, :type => :rvalue, :doc => <<-EOS
+This function returns an array an intersection of two.
+
+*Examples:*
+
+    intersection(["a","b","c"],["b","c","d"])
+
+Would return: ["b","c"]
+    EOS
+  ) do |arguments|
+
+    # Two arguments are required
+    raise(Puppet::ParseError, "intersection(): Wrong number of arguments " +
+      "given (#{arguments.size} for 2)") if arguments.size != 2
+
+    first = arguments[0]
+    second = arguments[1]
+
+    unless first.is_a?(Array) && second.is_a?(Array)
+      raise(Puppet::ParseError, 'intersection(): Requires 2 arrays')
+    end
+
+    result = first & second
+
+    return result
+  end
+end
+
+# vim: set ts=2 sw=2 et :

lib/puppet/parser/functions/union.rb

@@ -0,0 +1,34 @@
+#
+# union.rb
+#
+
+module Puppet::Parser::Functions
+  newfunction(:union, :type => :rvalue, :doc => <<-EOS
+This function returns a union of two arrays.
+
+*Examples:*
+
+    union(["a","b","c"],["b","c","d"])
+
+Would return: ["a","b","c","d"]
+    EOS
+  ) do |arguments|
+
+    # Two arguments are required
+    raise(Puppet::ParseError, "union(): Wrong number of arguments " +
+      "given (#{arguments.size} for 2)") if arguments.size != 2
+
+    first = arguments[0]
+    second = arguments[1]
+
+    unless first.is_a?(Array) && second.is_a?(Array)
+      raise(Puppet::ParseError, 'union(): Requires 2 arrays')
+    end
+
+    result = first | second
+
+    return result
+  end
+end
+
+# vim: set ts=2 sw=2 et :

spec/unit/puppet/parser/functions/difference_spec.rb

@@ -0,0 +1,19 @@
+#! /usr/bin/env ruby -S rspec
+require 'spec_helper'
+
+describe "the difference function" do
+  let(:scope) { PuppetlabsSpec::PuppetInternals.scope }
+
+  it "should exist" do
+    Puppet::Parser::Functions.function("difference").should == "function_difference"
+  end
+
+  it "should raise a ParseError if there are fewer than 2 arguments" do
+    lambda { scope.function_difference([]) }.should( raise_error(Puppet::ParseError) )
+  end
+
+  it "should return the difference between two arrays" do
+    result = scope.function_difference([["a","b","c"],["b","c","d"]])
+    result.should(eq(["a"]))
+  end
+end

spec/unit/puppet/parser/functions/intersection_spec.rb

@@ -0,0 +1,19 @@
+#! /usr/bin/env ruby -S rspec
+require 'spec_helper'
+
+describe "the intersection function" do
+  let(:scope) { PuppetlabsSpec::PuppetInternals.scope }
+
+  it "should exist" do
+    Puppet::Parser::Functions.function("intersection").should == "function_intersection"
+  end
+
+  it "should raise a ParseError if there are fewer than 2 arguments" do
+    lambda { scope.function_intersection([]) }.should( raise_error(Puppet::ParseError) )
+  end
+
+  it "should return the intersection of two arrays" do
+    result = scope.function_intersection([["a","b","c"],["b","c","d"]])
+    result.should(eq(["b","c"]))
+  end
+end

spec/unit/puppet/parser/functions/union_spec.rb

@@ -0,0 +1,19 @@
+#! /usr/bin/env ruby -S rspec
+require 'spec_helper'
+
+describe "the union function" do
+  let(:scope) { PuppetlabsSpec::PuppetInternals.scope }
+
+  it "should exist" do
+    Puppet::Parser::Functions.function("union").should == "function_union"
+  end
+
+  it "should raise a ParseError if there are fewer than 2 arguments" do
+    lambda { scope.function_union([]) }.should( raise_error(Puppet::ParseError) )
+  end
+
+  it "should join two arrays together" do
+    result = scope.function_union([["a","b","c"],["b","c","d"]])
+    result.should(eq(["a","b","c","d"]))
+  end
+end