doc/concatenating.txt

   1 PREV: doing_math.txt                                      NEXT: crop.txt
   2
   3 Cat the Planet!
   4
   5
   6 CAT: Horizontally concatenate. Vectors are treated as column matrices.
   7
   8                               / [1]  [4] \     [1 4]
   9  cat((1,2,3), (4,5,6)) = cat |  [2]  [5]  | =  [2 5]
  10                               \ [3], [6] /     [3 6]
  11
  12 VCAT: Vertical (or vector-wise) concatenation.
  13
  14                                             [1]
  15                            / [1]  [3] \     [2]
  16  vcat((1,2), (3,4)) = vcat \ [2], [4] /  =  [3]  = (1,2,3,4)
  17                                             [4]
  18
  19
  20 The following examples utilize the "store" function to build all
  21 variables from the result of different concatenations.
  22
  23 ------------------------------------------------------------------------
  24
  25  store("A", cat(3,5,7))
  26
  27                 (store "A" (cat 3 5 7))
  28
  29  ==>  [3 5 7]
  30
  31 Join the numbers to make a row matrix.
  32
  33 ------------------------------------------------------------------------
  34
  35  store("u", vcat(1,2,3))
  36
  37                 (store "u" (vcat 1 2 3))
  38
  39  ==>  (1, 2, 3)
  40
  41 This time, the result is a vector. Stored as /u/
  42
  43 ------------------------------------------------------------------------
  44
  45  cat(u,A)
  46                 (cat u A)
  47
  48       [1 3 5 7]
  49  ==>  [2 0 0 0]
  50       [3 0 0 0]
  51
  52 The column vector /u/ joins with /A/ by allocating the needed rows of
  53 zeros.
  54
  55 ------------------------------------------------------------------------
  56
  57  cat(A,u)
  58                 (cat A u)
  59
  60       [3 5 7 1]
  61  ==>  [0 0 0 2]
  62       [0 0 0 3]
  63
  64 /u/ joined with A from the other side.
  65
  66 ------------------------------------------------------------------------
  67
  68  cat(u,A)
  69                 (vcat u A)
  70       [1 2 3]
  71  ==>  [3 5 7]
  72
  73 Vertical concatenation using the transpose of the column vector /u/.
  74 vcat will always transpose vectors to be horizontal when called with a
  75 matrix.
  76 I figure this is the "best" behavior.
  77
  78 ------------------------------------------------------------------------
  79
  80  vcat(vcat(3,4,5), vcat(6,7,8,9))
  81
  82                 (vcat (vcat 3 4 5) (vcat 6 7 8 9))
  83
  84  ==>  (3, 4, 5, 6, 7, 8, 9)
  85
  86 Create 2 vectors: (3, 4, 5) and (6, 7, 8, 9)
  87 and through vcat, join them.
  88
  89 ------------------------------------------------------------------------
  90
  91  cat(vcat(3,4,5), vcat(6,7,8,9))
  92
  93                 (cat (vcat 3 4 5) (vcat 6 7 8 9))
  94
  95        [3 6]
  96        [4 7]
  97   ==>  [5 8]
  98        [0 9]
  99
 100 Using cat instead gives the two vectors stacked as columns in a matrix.
 101 Note the extra zero given to the left column.
 102
 103 ------------------------------------------------------------------------
 104
 105  store("B", vcat(cat(1,2), cat(3,4)))
 106
 107                 (store "B" (vcat (cat 1 2) (cat 3 4)))
 108
 109       [1 2]
 110  ==>  [3 4]
 111
 112 If you want to make a matrix by rows via cat, use this format. Of
 113 course, here we also store the result as matrix /B/.
 114
 115
 116 Of course, it only follows that matrices can be joined in the same way.
 117
 118 ------------------------------------------------------------------------
 119
 120  cat(A,B)
 121                 (cat A B)
 122
 123       [3 5 7 1 2]
 124  ==>  [0 0 0 3 4]
 125
 126 /A/ on the left,
 127 /B/ on the right.
 128
 129 ------------------------------------------------------------------------
 130
 131  vcat(A,B)
 132                 (vcat A B)
 133
 134       [3 5 7]
 135  ==>  [1 2 0]
 136       [3 4 0]
 137
 138 /A/ on top,
 139 /B/ below.
 140
 141 ------------------------------------------------------------------------
 142
 143 Lineal interprets some interesting
 144 number/matrix concatenation as well...
 145
 146 ------------------------------------------------------------------------
 147
 148  cat(9,B)
 149                 (cat 9 B)
 150
 151       [9 1 2]
 152  ==>  [9 3 4]
 153
 154 Add a column of 9's onto the left of /B/.
 155
 156 ------------------------------------------------------------------------
 157
 158  vcat(B,9)
 159                 (vcat B 9)
 160
 161       [1 2]
 162  ==>  [3 4]
 163       [9 9]
 164
 165 Add a row of 9's onto the bottom of /B/.
 166
 167 ------------------------------------------------------------------------
 168
 169  store("S", cat(4, vcat(4,5)))
 170
 171                 (store "S" (cat 4 (vcat 4 5)))
 172
 173       [4 4]
 174  ==>  [4 5]
 175
 176 Make a symmetric matrix /S/.
 177
 178 ------------------------------------------------------------------------
 179
 180  store("S", cat(3, vcat(3,S)))
 181
 182                 (store "S" (cat 3 (vcat 3 S)))
 183
 184       [3 3 3]
 185  ==>  [3 4 4]
 186       [3 4 5]
 187
 188 Build on a row of 3's atop /S/ then a column of 3's onto its left side.
 189
 190 ------------------------------------------------------------------------
 191
 192  store("S", cat(1, vcat(1, (cat 2, vcat(2, S)))))
 193
 194                 (store "S" (cat 1 (vcat 1 (cat 2 (vcat 2 S)))))
 195
 196       [1 1 1 1 1]
 197       [1 2 2 2 2]
 198  ==>  [1 2 3 3 3]
 199       [1 2 3 4 4]
 200       [1 2 3 4 5]
 201
 202 Finish off the symmetric pattern. Re-store it as /S/.
 203
 204 ------------------------------------------------------------------------
 205
 206 This concept holds with vectors too! But results may be surprising.
 207 Which is why vcat = vertical and cat = horizontal.
 208
 209 ------------------------------------------------------------------------
 210
 211  cat(7,u)
 212                 (cat 7 u)
 213
 214       [7 1]
 215  ==>  [7 2]
 216       [7 3]
 217
 218 /u/ is treated like a matrix.
 219 If you wanted (7, 1, 2, 3), use (vcat 7 u).
 220
 221 ------------------------------------------------------------------------
 222
 223 And in some situations, results may be very surprising...
 224
 225 ------------------------------------------------------------------------
 226
 227  cat(7, u, 8)
 228                 (cat 7 u 8)
 229
 230       [7 1 8]
 231  ==>  [7 2 8]
 232       [7 3 8]
 233
 234 OK, so that's not too surprising since Lineal has a lot of functions
 235 which take an arbitrary number of terms.
 236
 237 ------------------------------------------------------------------------
 238
 239  cat(6,7,u,8)
 240                 (cat 6 7 u 8)
 241
 242       [6 7 1 8]
 243  ==>  [6 7 2 8]
 244       [6 7 3 8]
 245
 246 Again, nothing too out of the ordinary.
 247
 248 ------------------------------------------------------------------------
 249
 250  cat(7,u,8,9)
 251                 (cat 7 u 8 9)
 252
 253       [7 1 8 9]
 254  ==>  [7 2 0 0]
 255       [7 3 0 0]
 256
 257 A little strange. This happens because the cat and vcat functions build
 258 from right to left.  Here, it is equivalent to calling
 259   (cat 7 (cat u (cat 8 9)))
 260 where
 261   (cat 8 9)
 262 returns a row matrix [8 9] and so on.
 263
 264 ------------------------------------------------------------------------
 265  vim:ft=:expandtab:tw=72: