Description of sladd

Home > sltoolbox > core > sladd.m

sladd

PURPOSE

SLADD Add a sub-array along some dimensions to an array

SYNOPSIS

function Ar = sladd(A0, As, d)

DESCRIPTION

SLADD Add a sub-array along some dimensions to an array

 $ Syntax $
   - Ar = sladd(A0, As)
   - Ar = sladd(A0, As, d)

 $ Arguments $
   - A0:           the original array
   - v:            the sub-array to be added to the array
   - Ar:           the resultant array
   - d:            the dimension along which the vector is added

 $ Description $
   - Ar = sladd(A0, As) adds the sub-array As to the array A0 along 
     auto-selected dimensions. The dimensions are identified by the 
     dimension of As with size larger than 1. If As is a scalar, then 
     all elements of A0 will be added As.
   
   - Ar = sladd(A0, As, d) adds the sub-array As to the array A0 along
     the dimensions specified by d. 

 $ Remarks $
   # An empty As is allowed. In such case, the original array A0 will
     be output, i.e. Ar = A0.
   # The sizes of dimensions along which the sub-array is added should
     match that of A0, otherwise, an error will be raised.
   # By specifying the dimensions through d, the speed can be accelerated.

 $ Examples $
   - Add a vector to a matrix.
     \{
         A = [1 2 3; 4 5 6];
         v = [2; 5];
         Ar = sladd(A, v)
     
         Ar = 

             3     4     5         
             9    10    11

     \}
     It is equivalent to sladd(A, v, 1).

  - Add a plane to a matrix
    \{
        A1 = [1 2 3; 4 5 6];
        A2 = [7 8 9; 10 11 12];
        A = cat(3, A1, A2);
        v1 = [10; 20];
        v2 = [30; 40];
        As = cat(3, v1, v2)

        Ar(:, :, 1) = 
            
            11    12    13
            24    25    26

        Ar(:, :, 2) = 

            37    38    39
            50    51    52

    \}

 $ History $
   - Created by Dahua Lin on Nov 18th, 2005

CROSS-REFERENCE INFORMATION

This function calls:

• raise_lackinput RAISE_LACKINPUT Raises an error indicating lack of input argument

This function is called by:

SOURCE CODE

0001 function Ar = sladd(A0, As, d)
0002 %SLADD Add a sub-array along some dimensions to an array
0003 %
0004 % $ Syntax $
0005 %   - Ar = sladd(A0, As)
0006 %   - Ar = sladd(A0, As, d)
0007 %
0008 % $ Arguments $
0009 %   - A0:           the original array
0010 %   - v:            the sub-array to be added to the array
0011 %   - Ar:           the resultant array
0012 %   - d:            the dimension along which the vector is added
0013 %
0014 % $ Description $
0015 %   - Ar = sladd(A0, As) adds the sub-array As to the array A0 along
0016 %     auto-selected dimensions. The dimensions are identified by the
0017 %     dimension of As with size larger than 1. If As is a scalar, then
0018 %     all elements of A0 will be added As.
0019 %
0020 %   - Ar = sladd(A0, As, d) adds the sub-array As to the array A0 along
0021 %     the dimensions specified by d.
0022 %
0023 % $ Remarks $
0024 %   # An empty As is allowed. In such case, the original array A0 will
0025 %     be output, i.e. Ar = A0.
0026 %   # The sizes of dimensions along which the sub-array is added should
0027 %     match that of A0, otherwise, an error will be raised.
0028 %   # By specifying the dimensions through d, the speed can be accelerated.
0029 %
0030 % $ Examples $
0031 %   - Add a vector to a matrix.
0032 %     \{
0033 %         A = [1 2 3; 4 5 6];
0034 %         v = [2; 5];
0035 %         Ar = sladd(A, v)
0036 %
0037 %         Ar =
0038 %
0039 %             3     4     5
0040 %             9    10    11
0041 %
0042 %     \}
0043 %     It is equivalent to sladd(A, v, 1).
0044 %
0045 %  - Add a plane to a matrix
0046 %    \{
0047 %        A1 = [1 2 3; 4 5 6];
0048 %        A2 = [7 8 9; 10 11 12];
0049 %        A = cat(3, A1, A2);
0050 %        v1 = [10; 20];
0051 %        v2 = [30; 40];
0052 %        As = cat(3, v1, v2)
0053 %
0054 %        Ar(:, :, 1) =
0055 %
0056 %            11    12    13
0057 %            24    25    26
0058 %
0059 %        Ar(:, :, 2) =
0060 %
0061 %            37    38    39
0062 %            50    51    52
0063 %
0064 %    \}
0065 %
0066 % $ History $
0067 %   - Created by Dahua Lin on Nov 18th, 2005
0068 %
0069 
0070 %% parse and verify input
0071 if nargin < 2
0072     raise_lackinput('sladd', 2);
0073 end
0074 if isempty(As)
0075     Ar = A0;
0076     return;
0077 end
0078 if ndims(As) > ndims(A0)
0079     error('sltoolbox:dimoverflow', ...
0080         'The dimension of As should not be larger than that of A0');
0081 end
0082 if nargin < 3 || isempty(d)
0083     % d is not specified, automatically determine d
0084     d = find(size(As) > 1);
0085 end
0086 siz_A0 = size(A0);
0087 siz_As = size(As);
0088 if ~isequal(siz_A0(d), siz_As(d))
0089     error('sltoolbox:dimmismatch', ...
0090         'The dimensions of As does not match that of A0 in the dimensions to be added');
0091 end
0092 
0093 %% compute
0094 siz_A0(d) = 1;
0095 Ar = A0 + repmat(As, siz_A0);
0096 
0097     
0098 
0099 
0100

---

Generated on Wed 20-Sep-2006 12:43:11 by m2html © 2003