calc/help/blk

NAME
    blk - generate or modify block values

SYNOPSIS
    blk([len, chunk]);
    blk(val [, len, chunk]);

TYPES
    len		null or integer
    chunk	null or integer
    val		non-null string, block, or named block

    return	block or named block

DESCRIPTION
    With only integer arguments, blk(len, chunk) attempts to
    allocate a block of memory consisting of N octets (unsigned 8-bit
    bytes).  Allocation is always done in multiples of chunk
    octets, so the actual allocation size of len rounded up
    to the next multiple of chunk.

    The default value for len is 0.  The default value for chunk is 256.

    If the allocation is successful, blk(len, chunk) returns a value B, say,
    for which the octets in the block may be referenced by B[0], B[1],
    ... , B[len-1], these all initially having zero value.

    The octets B[i] for i >= len always have zero value.  If B[i] with
    some i >= len is referenced, len is increased by 1.  For example:

			B[i] = x

    has an effect like that of two operations on a file stream fs:

			fseek(fs, pos);
			fputc(fs, x).

    Similarly:

			x = B[i]

    is like:

			fseek(fs, pos);
			x = fgetc(fs).

    The value of chunk is stored as the "chunksize" for B.

    The size(B) builtin returns the current len for the block; sizeof(B)
    returns its maxsize; memsize(B) returns maxsize + overhead for any block
    value.  Also size(B) is analogous to the length of a file stream in that
    if size(B) < sizeof(B):

			B[size(B)] = x

    will append one octet to B and increment size(B).

    The builtin test(B) returns 1 or 0 according as at least one octet
    is zero or all octets are zero.  If B1 and B2 are blocks, they are
    considered equal (B1 == B2) if they have the same length and the
    same data, i.e.  B1[i] == B2[i] for 0 <= i < len.  Chunksizes
    and maxsizes are ignored.

    The output for print B occupies two lines, the first line giving
    the chunksize, number of octets allocated (len rounded up to the
    next chunk) and len, and the second line up to 30 octets of data.
    If the datalen is zero, the second line is blank.  If the datalen
    exceeds 30, this indicated by a trailing "...".

    If a block value B created by B = blk(len, chunk) is assigned to
    another variable by C = B, a new block of the same structure as B
    is created to become the value of C, and the octets in B are copied
    to this new block.  A block with possibly different length or
    chunksize is created by C = blk(B, newlen, newchunk), only the first
    min(len, newlen) octets being copied from B; later octets are
    assigned zero value.  If omitted, newlen and newchunk default to
    the current datalen and chunk-size for B.  The curent datalen,
    chunksize and number of allocated octets for B may be changed by:

			B = blk(B, newlen, newchunk).

    No data is lost if newlen is greater than or equal to the old
    size(B).

    The memory block allocated by blk(len, chunk) is freed at or before
    termination of the statement in which this occurred, the memory
    allocated in B = blk(len, chunk) is freed when B is assigned another
    value.

    With a string str as its first argument, blk(str [, len, chunk])
    when called for the first time creates a block with str as its
    name.  Here there no restriction on the characters used in str;
    thus the string may include white space or characters normally used
    for punctuation or operators.  Any subsequent call to blk(str, ...)
    with the same str will refer to the same named block.

    A named block is assigned length and chunksize and consequent
    maximum size in the same way as unnamed blocks. A major difference
    is that in assignments, a named block is not copied.  Thus, if a
    block A has been created by:

			A = blk("foo")
    any subsequent:
			B = A
    or:
			B = blk("foo")

    will give a second variable B referring to the same block as A.
    Either  A[i] = x  or  B[i] = x  may then be used to assign a value
    to an octet in the book.   Its length or chunksize may be changed by
    instructions like:

			blk(A, len, chunk);

			A = blk(A, len, chunk);

			null(blk(A, len, chunk)).

    These have the same effect on A; when working interactively, the
    last two avoid printing of the new value for A.

    Named blocks are assigned index numbers 0, 1, 2, ..., in the order
    of their creation.  The block with index id is returned by blocks(id).
    With no argument, blocks() returns the number of current unfreed
    named blocks.  A named block may be used

    The memory allocated to a named block is freed by the blkfree()
    function with argument the named block, its name, or its id number.
    The block remains in existence but with a null data pointer,
    its length and size being reduced to zero.  A new block of memory
    may be allocated to it, with possibly new length and chunksize by:

			blk(val [, len, chunk])

    where val is either the named block or its name.

    The printing output for a named block is in three lines, the first
    line displaying its id number and name, the other two as for an
    unnamed block, except that "NULL" is printed if the memory has been
    freed.

    The identifying numbers and names of the current named blocks are
    displayed by:
			show blocks

    If A and B are named blocks, A == B will be true only if they refer
    to the same block of memory.  Thus, blocks with the same data and
    datalen will be considered unequal if they have different names.

    If A is a named block, str(A) returns the name of the block.

    Values may be assigned to the early octets of a named or unnamed
    block by use of = { } initialization as for matrices.

EXAMPLE

    > B = blk(15,10)

    > B[7] = 0xff
    > B
	chunksize = 10, maxsize = 20, datalen = 15
	00000000000000ff00000000000000

    > B[18] = 127
    > B
	chunksize = 10, maxsize = 20, datalen = 18
	00000000000000ff0000000000000000007f

    > B[20] = 2
    Index out of bounds for block

    > print size(B), sizeof(B)
    18 20

    > B = blk(B, 100, 20)
    > B
	chunksize = 20, maxsize = 120, datalen = 100
	00000000000000ff0000000000000000007f000000000000000000000000...

    > C = blk(B, 10} = {1,2,3}
    > C
	chunksize = 20, maxsize = 20, datalen = 10
	01020300000000ff0000

    > A1 = blk("alpha")
    > A1
	block 0: alpha
	chunksize = 256, maxsize = 256, datalen = 0

    > A1[7] = 0xff
    > A2 = A1
    > A2[17] = 127
    > A1
	block 0: alpha
	chunksize = 256, maxsize = 256, datalen = 18
	00000000000000ff0000000000000000007f

    > A1 = blk(A1, 1000)
    > A1
	block 0: alpha
	chunksize = 256, maxsize = 1024, datalen = 1000
	00000000000000ff0000000000000000007f000000000000000000000000...

    > A1 = blk(A1, , 16)
    > A1
	block 0: alpha
	chunksize = 16, maxsize = 1008, datalen = 1000
	00000000000000ff0000000000000000007f000000000000000000000000...

LIMITS
    0 <= len < 2^31

    1 <= chunk < 2^31

LIBRARY
    XXX

SEE ALSO
    blocks, blkfree