help/blkcpy

   1 NAME
   2     blkcpy, copy - copy items from a structure to a structure
   3
   4 SYNOPSIS
   5     blkcpy(dst, src [, num [, dsi [, ssi]]]
   6     copy(src, dest [, [ssi [, num [, dsi]]])
   7
   8 TYPES
   9     src         block, file, string, matrix, or list
  10     dest        block, file, matrix or list - compatible with src
  11
  12     ssi         nonnegative integer, defaults to zero
  13     num         nonnegative integer, defaults to maximum possible
  14     dsi         nonnegative integer, defaults to datalen for a block, filepos
  15                         for a file, zero for other structures
  16
  17     return      null if successful, error value otherwise
  18
  19 DESCRIPTION
  20     A call to:
  21
  22             blkcpy(dst, src, num, dsi, ssi)
  23
  24     attempts to copy 'num' consecutive items (octets or values) starting
  25     from the source item 'src' with index 'ssi'.  By default, 'num'
  26     is the maximum possible and 'ssi' is 0.
  27
  28     A call to:
  29
  30             copy(src, dst, ssi, num, dsi)
  31
  32     does the same thing, but with a different arg order.
  33
  34     A copy fails if ssi or num is too large for the number of items in
  35     the source, if sdi is too large for the number of positions
  36     available in the destination, or, in cases involving a file stream,
  37     if the file is not open in the required mode.  The source and
  38     destination need not be of the same type, e.g. when a block is
  39     copied to a matrix the octets are converted to numbers.
  40
  41     The following pairs of source-type, destination-type are permitted:
  42
  43                 block to
  44                          int
  45                          block
  46                          matrix
  47                          file
  48
  49                 matrix to
  50                          block
  51                          matrix
  52                          list
  53
  54                 string to
  55                          block
  56                          file
  57
  58                 list to
  59                          list
  60                          matrix
  61
  62                 file to
  63                          block
  64
  65                 int to
  66                          block
  67
  68     In the above table, int refers to integer values.  However if a
  69     rational value is supplied, only the numerator is copied.
  70
  71     Each copied octet or value replaces the octet or value in the
  72     corresponding place in the destination structure.  When copying values
  73     to values, the new values are stored in a buffer, the old values are
  74     removed, and the new values copied from the buffer to the destination.
  75     This permits movement of data within one matrix or list, and copying
  76     of an element of structure to the structure.
  77
  78     Except for copying to files or blocks, the destination is already to have
  79     sufficient memory allocated for the copying.  For example, to copy
  80     a matrix M of size 100 to a newly created list, one may use:
  81
  82                         L = makelist(100);
  83                         copy(M, L);
  84    or:
  85                         L = makelist(100);
  86                         blkcpy(L, M);
  87
  88     For copying from a block B (named or unnamed), the total number of octets
  89     available for copying is taken to the the datalen for that block,
  90     so that num can be at most size(B) - ssi.
  91
  92     For copying to a block B (named or unnamed), reallocation will be
  93     required if dsi + num > sizeof(B).  (This will not be permitted if
  94     protect(B) has bit 4 set.)
  95
  96     For copying from a file stream fs, num can be at most size(fs) - ssi.
  97
  98     For copying from a string str, the string is taken to include the
  99     terminating '\0', so the total number of octets available is
 100     strlen(str) + 1 and num can be at most strlen(str) + 1 - ssi.
 101     If num <= strlen(str) - ssi, the '\0' is not copied.
 102
 103     For copying from or to a matrix M, the total number of values in
 104     M is size(M), so in the source case, num <= size(M) - ssi, and
 105     in the destination case, num <= size(M) - dsi.  The indices ssi
 106     and dsi refer to the double-bracket method of indexing, i.e. the
 107     matrix is as if its elements were indexed 0, 1, ..., size(M) - 1.
 108
 109
 110 EXAMPLE
 111     > A = blk() = {1,2,3,4}
 112     > B = blk()
 113     > blkcpy(B,A)
 114     > B
 115         chunksize = 256, maxsize = 256, datalen = 4
 116         01020304
 117     >
 118     > blkcpy(B,A)
 119     > B
 120         chunksize = 256, maxsize = 256, datalen = 8
 121         0102030401020304
 122     > blkcpy(B, A, 2, 10)
 123     > B
 124         chunksize = 256, maxsize = 256, datalen = 12
 125         010203040102030400000102
 126     > blkcpy(B,32767)
 127     > B
 128         chunksize = 256, maxsize = 256, datalen = 16
 129         010203040102030400000102ff7f0000
 130     > mat M[2,2]
 131     > blkcpy(M, A)
 132     > M
 133         mat [2,2] (4 elements, 4 nonzero):
 134           [0,0] = 1
 135           [0,1] = 2
 136           [1,0] = 3
 137           [1,1] = 4
 138     > blkcpy(M, A, 2, 2)
 139     > M
 140         mat [2,2] (4 elements, 4 nonzero):
 141           [0,0] = 1
 142           [0,1] = 2
 143           [1,0] = 1
 144           [1,1] = 2
 145
 146     > A = blk() = {1,2,3,4}
 147     > B = blk()
 148     > copy(A,B)
 149     > B
 150         chunksize = 256, maxsize = 256, datalen = 4
 151         01020304
 152     > copy(A,B)
 153     > B
 154         chunksize = 256, maxsize = 256, datalen = 8
 155         0102030401020304
 156     > copy(A,B,1,2)
 157     > B
 158         chunksize = 256, maxsize = 256, datalen = 10
 159         01020304010203040203
 160     > mat M[2,2]
 161     > copy(A,M)
 162     > M
 163         mat [2,2] (4 elements, 4 nonzero):
 164           [0,0] = 1
 165           [0,1] = 2
 166           [1,0] = 3
 167           [1,1] = 4
 168
 169     > copy(A,M,2)
 170     > M
 171         mat [2,2] (4 elements, 4 nonzero):
 172           [0,0] = 3
 173           [0,1] = 4
 174           [1,0] = 3
 175           [1,1] = 4
 176
 177     > copy(A,M,0,2,2)
 178     > M
 179         mat [2,2] (4 elements, 4 nonzero):
 180           [0,0] = 3
 181           [0,1] = 4
 182           [1,0] = 1
 183           [1,1] = 2
 184
 185 LIMITS
 186     none
 187
 188 LINK LIBRARY
 189     none
 190
 191 SEE ALSO
 192     blk, mat, file, list, str
 193