help/blk

   1 NAME
   2     blk - generate or modify block values
   3
   4 SYNOPSIS
   5     blk([len, chunk]);
   6     blk(val [, len, chunk]);
   7
   8 TYPES
   9     len         null or integer
  10     chunk       null or integer
  11     val         non-null string, block, or named block
  12
  13     return      block or named block
  14
  15 DESCRIPTION
  16     With only integer arguments, blk(len, chunk) attempts to
  17     allocate a block of memory consisting of N octets (unsigned 8-bit
  18     bytes).  Allocation is always done in multiples of chunk
  19     octets, so the actual allocation size of len rounded up
  20     to the next multiple of chunk.
  21
  22     The default value for len is 0.  The default value for chunk is 256.
  23
  24     If the allocation is successful, blk(len, chunk) returns a value B, say,
  25     for which the octets in the block may be referenced by B[0], B[1],
  26     ... , B[len-1], these all initially having zero value.
  27
  28     The octets B[i] for i >= len always have zero value.  If B[i] with
  29     some i >= len is referenced, len is increased by 1.  For example:
  30
  31                         B[i] = x
  32
  33     has an effect like that of two operations on a file stream fs:
  34
  35                         fseek(fs, pos);
  36                         fputc(fs, x).
  37
  38     Similarly:
  39
  40                         x = B[i]
  41
  42     is like:
  43
  44                         fseek(fs, pos);
  45                         x = fgetc(fs).
  46
  47     The value of chunk is stored as the "chunksize" for B.
  48
  49     The size(B) builtin returns the current len for the block; sizeof(B)
  50     returns its maxsize; memsize(B) returns maxsize + overhead for any block
  51     value.  Also size(B) is analogous to the length of a file stream in that
  52     if size(B) < sizeof(B):
  53
  54                         B[size(B)] = x
  55
  56     will append one octet to B and increment size(B).
  57
  58     The builtin test(B) returns 1 or 0 according as at least one octet
  59     is zero or all octets are zero.  If B1 and B2 are blocks, they are
  60     considered equal (B1 == B2) if they have the same length and the
  61     same data, i.e.  B1[i] == B2[i] for 0 <= i < len.  Chunksizes
  62     and maxsizes are ignored.
  63
  64     The output for print B occupies two lines, the first line giving
  65     the chunksize, number of octets allocated (len rounded up to the
  66     next chunk) and len, and the second line up to 30 octets of data.
  67     If the datalen is zero, the second line is blank.  If the datalen
  68     exceeds 30, this indicated by a trailing "...".
  69
  70     If a block value B created by B = blk(len, chunk) is assigned to
  71     another variable by C = B, a new block of the same structure as B
  72     is created to become the value of C, and the octets in B are copied
  73     to this new block.  A block with possibly different length or
  74     chunksize is created by C = blk(B, newlen, newchunk), only the first
  75     min(len, newlen) octets being copied from B; later octets are
  76     assigned zero value.  If omitted, newlen and newchunk default to
  77     the current datalen and chunk-size for B.  The current datalen,
  78     chunksize and number of allocated octets for B may be changed by:
  79
  80                         B = blk(B, newlen, newchunk).
  81
  82     No data is lost if newlen is greater than or equal to the old
  83     size(B).
  84
  85     The memory block allocated by blk(len, chunk) is freed at or before
  86     termination of the statement in which this occurred, the memory
  87     allocated in B = blk(len, chunk) is freed when B is assigned another
  88     value.
  89
  90     With a string str as its first argument, blk(str [, len, chunk])
  91     when called for the first time creates a block with str as its
  92     name.  Here there no restriction on the characters used in str;
  93     thus the string may include white space or characters normally used
  94     for punctuation or operators.  Any subsequent call to blk(str, ...)
  95     with the same str will refer to the same named block.
  96
  97     A named block is assigned length and chunksize and consequent
  98     maximum size in the same way as unnamed blocks. A major difference
  99     is that in assignments, a named block is not copied.  Thus, if a
 100     block A has been created by:
 101
 102                         A = blk("foo")
 103     any subsequent:
 104                         B = A
 105     or:
 106                         B = blk("foo")
 107
 108     will give a second variable B referring to the same block as A.
 109     Either  A[i] = x  or  B[i] = x  may then be used to assign a value
 110     to an octet in the book.   Its length or chunksize may be changed by
 111     instructions like:
 112
 113                         blk(A, len, chunk);
 114
 115                         A = blk(A, len, chunk);
 116
 117                         null(blk(A, len, chunk)).
 118
 119     These have the same effect on A; when working interactively, the
 120     last two avoid printing of the new value for A.
 121
 122     Named blocks are assigned index numbers 0, 1, 2, ..., in the order
 123     of their creation.  The block with index id is returned by blocks(id).
 124     With no argument, blocks() returns the number of current unfreed
 125     named blocks.
 126
 127     The memory allocated to a named block is freed by the blkfree()
 128     function with argument the named block, its name, or its id number.
 129     The block remains in existence but with a null data pointer,
 130     its length and size being reduced to zero.  A new block of memory
 131     may be allocated to it, with possibly new length and chunksize by:
 132
 133                         blk(val [, len, chunk])
 134
 135     where val is either the named block or its name.
 136
 137     The printing output for a named block is in three lines, the first
 138     line displaying its id number and name, the other two as for an
 139     unnamed block, except that "NULL" is printed if the memory has been
 140     freed.
 141
 142     The identifying numbers and names of the current named blocks are
 143     displayed by:
 144                         show blocks
 145
 146     If A and B are named blocks, A == B will be true only if they refer
 147     to the same block of memory.  Thus, blocks with the same data and
 148     datalen will be considered unequal if they have different names.
 149
 150     If A is a named block, str(A) returns the name of the block.
 151
 152     Values may be assigned to the early octets of a named or unnamed
 153     block by use of = { } initialization as for matrices.
 154
 155 EXAMPLE
 156
 157     > B = blk(15,10)
 158
 159     > B[7] = 0xff
 160     > B
 161         chunksize = 10, maxsize = 20, datalen = 15
 162         00000000000000ff00000000000000
 163
 164     > B[18] = 127
 165     > B
 166         chunksize = 10, maxsize = 20, datalen = 18
 167         00000000000000ff0000000000000000007f
 168
 169     > B[20] = 2
 170     Index out of bounds for block
 171
 172     > print size(B), sizeof(B)
 173     18 20
 174
 175     > B = blk(B, 100, 20)
 176     > B
 177         chunksize = 20, maxsize = 120, datalen = 100
 178         00000000000000ff0000000000000000007f000000000000000000000000...
 179
 180     > C = blk(B, 10} = {1,2,3}
 181     > C
 182         chunksize = 20, maxsize = 20, datalen = 10
 183         01020300000000ff0000
 184
 185     > A1 = blk("alpha")
 186     > A1
 187         block 0: alpha
 188         chunksize = 256, maxsize = 256, datalen = 0
 189
 190     > A1[7] = 0xff
 191     > A2 = A1
 192     > A2[17] = 127
 193     > A1
 194         block 0: alpha
 195         chunksize = 256, maxsize = 256, datalen = 18
 196         00000000000000ff0000000000000000007f
 197
 198     > A1 = blk(A1, 1000)
 199     > A1
 200         block 0: alpha
 201         chunksize = 256, maxsize = 1024, datalen = 1000
 202         00000000000000ff0000000000000000007f000000000000000000000000...
 203
 204     > A1 = blk(A1, , 16)
 205     > A1
 206         block 0: alpha
 207         chunksize = 16, maxsize = 1008, datalen = 1000
 208         00000000000000ff0000000000000000007f000000000000000000000000...
 209
 210 LIMITS
 211     0 <= len < 2^31
 212
 213     1 <= chunk < 2^31
 214
 215 LINK LIBRARY
 216     XXX
 217
 218 SEE ALSO
 219     blocks, blkfree
 220