c_cpp/etc/calc/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 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     ; blkcpy(B,A)
 118     ; B
 119         chunksize = 256, maxsize = 256, datalen = 8
 120         0102030401020304
 121     ; blkcpy(B, A, 2, 10)
 122     ; B
 123         chunksize = 256, maxsize = 256, datalen = 12
 124         010203040102030400000102
 125     ; blkcpy(B,32767)
 126     ; B
 127         chunksize = 256, maxsize = 256, datalen = 16
 128         010203040102030400000102ff7f0000
 129     ; mat M[2,2]
 130     ; blkcpy(M, A)
 131     ; M
 132         mat [2,2] (4 elements, 4 nonzero):
 133           [0,0] = 1
 134           [0,1] = 2
 135           [1,0] = 3
 136           [1,1] = 4
 137     ; blkcpy(M, A, 2, 2)
 138     ; M
 139         mat [2,2] (4 elements, 4 nonzero):
 140           [0,0] = 1
 141           [0,1] = 2
 142           [1,0] = 1
 143           [1,1] = 2
 144
 145     ; A = blk() = {1,2,3,4}
 146     ; B = blk()
 147     ; copy(A,B)
 148     ; B
 149         chunksize = 256, maxsize = 256, datalen = 4
 150         01020304
 151     ; copy(A,B)
 152     ; B
 153         chunksize = 256, maxsize = 256, datalen = 8
 154         0102030401020304
 155     ; copy(A,B,1,2)
 156     ; B
 157         chunksize = 256, maxsize = 256, datalen = 10
 158         01020304010203040203
 159     ; mat M[2,2]
 160     ; copy(A,M)
 161     ; M
 162         mat [2,2] (4 elements, 4 nonzero):
 163           [0,0] = 1
 164           [0,1] = 2
 165           [1,0] = 3
 166           [1,1] = 4
 167
 168     ; copy(A,M,2)
 169     ; M
 170         mat [2,2] (4 elements, 4 nonzero):
 171           [0,0] = 3
 172           [0,1] = 4
 173           [1,0] = 3
 174           [1,1] = 4
 175
 176     ; copy(A,M,0,2,2)
 177     ; M
 178         mat [2,2] (4 elements, 4 nonzero):
 179           [0,0] = 3
 180           [0,1] = 4
 181           [1,0] = 1
 182           [1,1] = 2
 183
 184 LIMITS
 185     none
 186
 187 LINK LIBRARY
 188     none
 189
 190 SEE ALSO
 191     blk, mat, file, list, str
 192
 193 ## Copyright (C) 1999-2006  Landon Curt Noll
 194 ##
 195 ## Calc is open software; you can redistribute it and/or modify it under
 196 ## the terms of the version 2.1 of the GNU Lesser General Public License
 197 ## as published by the Free Software Foundation.
 198 ##
 199 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 200 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 201 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 202 ## Public License for more details.
 203 ##
 204 ## A copy of version 2.1 of the GNU Lesser General Public License is
 205 ## distributed with calc under the filename COPYING-LGPL.  You should have
 206 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 207 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 208 ##
 209 ## @(#) $Revision: 30.2 $
 210 ## @(#) $Id: blkcpy,v 30.2 2013/08/11 01:08:32 chongo Exp $
 211 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/blkcpy,v $
 212 ##
 213 ## Under source code control:   1997/04/05 14:08:50
 214 ## File existed as early as:    1997
 215 ##
 216 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 217 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/