mirror of
https://github.com/lcn2/calc.git
synced 2025-08-16 01:03:29 +03:00
Release calc version 2.10.3t5.45
This commit is contained in:
Landon Curt Noll
219
help/blk
Normal file
219
help/blk
Normal file
@@ -0,0 +1,219 @@
|
||||
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
|
||||
Reference in New Issue
Block a user