@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Sets
@chapter Sets

Octave has a limited set of functions for managing sets of data, where a
set is defined as a collection of unique elements.  In Octave a set is
represented as a vector of numbers.

@anchor{doc-create_set}
@deftypefn {Function File} {} create_set (@var{x})
Return a row vector containing the unique values in @var{x}, sorted in
ascending order.  For example,

@example
@group
create_set ([ 1, 2; 3, 4; 4, 2 ])
@result{} [ 1, 2, 3, 4 ]
@end group
@end example
@seealso{union, intersection, complement}
@end deftypefn


@anchor{doc-unique}
@deftypefn {Function File} {} unique (@var{x})

Return the unique elements of @var{x}, sorted in ascending order.
If @var{x} is a row vector, return a row vector, but if @var{x}
is a column vector or a matrix return a column vector.

@deftypefnx {Function File} {} unique (@var{A}, 'rows')

Return the unique rows of @var{A}, sorted in ascending order.

@deftypefnx {Function File} {[@var{y}, @var{i}, @var{j}] = } unique (@var{x})

Return index vectors @var{i} and @var{j} such that @code{x(i)==y} and
@code{y(j)==x}.
@seealso{union, intersect, setdiff, setxor, ismember}
@end deftypefn


@menu
* Set Operations:: 
@end menu

@node Set Operations
@section Set Operations

Octave supports the basic set operations.  That is, Octave can compute
the union, intersection, complement, and difference of two sets.
Octave can also supports the @emph{Exclusive Or} set operation, and
membership determination.  The functions for set operations all work in
pretty much the same way.  As an example, assume that @code{x} and
@code{y} contains two sets, then

@example
union(x, y)
@end example

@noindent
computes the union of the two sets.

@anchor{doc-ismember}
@deftypefn {Function File} {[@var{tf}, @var{a_idx}] =} ismember (@var{A}, @var{S}) 
@deftypefnx {Function File} {[@var{tf}, @var{a_idx}] =} ismember (@var{A}, @var{S}, "rows")
Return a matrix @var{tf} the same shape as @var{A} which has 1 if 
@code{A(i,j)} is in @var{S} or 0 if it isn't. If a second output argument 
is requested, the indexes into @var{S} of the matching elements are
also returned. 

@example
@group
a = [3, 10, 1];
s = [0:9];
[tf, a_idx] = residue (a, s);
@result{} tf = [1, 0, 1]
@result{} a_idx = [4, 0, 2]
@end group
@end example

The inputs, @var{A} and @var{S}, may also be cell arrays.

@example
@group
a = @{'abc'@};
s = @{'abc', 'def'@};
[tf, a_idx] = residue (a, s);
@result{} tf = [1, 0]
@result{} a_idx = [1, 0]
@end group
@end example

With the optional third argument @code{"rows"}, and matrices 
@var{A} and @var{S} with the same number of columns, compare rows in
@var{A} with the rows in @var{S}.

@example
@group
a = [1:3; 5:7; 4:6];
s = [0:2; 1:3; 2:4; 3:5; 4:6];
[tf, a_idx] = ismember(a, s, 'rows');
@result{} tf = logical ([1; 0; 1])
@result{} a_idx = [2; 0; 5];
@end group
@end example

@seealso{unique, union, intersection, setxor, setdiff}
@end deftypefn


@anchor{doc-union}
@deftypefn {Function File} {} union (@var{x}, @var{y})
Return the set of elements that are in either of the sets @var{x} and
@var{y}.  For example,

@example
@group
union ([ 1, 2, 4 ], [ 2, 3, 5 ])
@result{} [ 1, 2, 3, 4, 5 ]
@end group
@end example
@seealso{create_set, intersection, complement}
@end deftypefn


@anchor{doc-intersect}
@deftypefn {Function File} {} intersect (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@var{a}, @var{b})

Return the elements in both @var{a} and @var{b}, sorted in ascending
order. If @var{a} and @var{b} are both column vectors return a column
vector, otherwise return a row vector.

Return index vectors @var{ia} and @var{ib} such that @code{a(ia)==c} and
@code{b(ib)==c}.

@end deftypefn
@seealso{unique, union, setxor, setdiff, ismember}


@anchor{doc-complement}
@deftypefn {Function File} {} complement (@var{x}, @var{y})
Return the elements of set @var{y} that are not in set @var{x}.  For
example,

@example
@group
complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
@result{} 5
@end group
@end example
@seealso{create_set, union, intersection}
@end deftypefn


@anchor{doc-setdiff}
@deftypefn {Function File} {} setdiff (@var{a}, @var{b})
@deftypefnx {Function File} {} setdiff (@var{a}, @var{b}, "rows")
Return the elements in @var{a} that are not in @var{b}, sorted in
ascending order.  If @var{a} and @var{b} are both column vectors
return a column vector, otherwise return a row vector.

Given the optional third argument @samp{"rows"}, return the rows in
@var{a} that are not in @var{b}, sorted in ascending order by rows.
@seealso{unique, union, intersect, setxor, ismember}
@end deftypefn


@anchor{doc-setxor}
@deftypefn {Function File} {} setxor (@var{a}, @var{b})

Return the elements exclusive to @var{a} or @var{b}, sorted in ascending
order. If @var{a} and @var{b} are both column vectors return a column
vector, otherwise return a row vector.

@seealso{unique, union, intersect, setdiff, ismember}
@end deftypefn

