mirror of
https://github.com/lcn2/calc.git
synced 2025-08-19 01:13:27 +03:00
a31078bbec
Some folks might think: “you still use RCS”?!? And we will say, hey, at least we switched from SCCS to RCS back in … I think it was around 1994 ... at least we are keeping up! :-) :-) :-) Logs say that SCCS version 18 became RCS version 19 on 1994 March 18. RCS served us well. But now it is time to move on. And so we are switching to git. Calc releases produce a lot of file changes. In the 125 releases of calc since 1996, when I started managing calc releases, there have been 15473 file mods!
257 lines
8.4 KiB
Plaintext
257 lines
8.4 KiB
Plaintext
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 len 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, size(B) is increased to i + 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 nonzero 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 current 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 block. 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.
|
|
|
|
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
|
|
|
|
LINK LIBRARY
|
|
BLOCK *blkalloc(int len, int chunk)
|
|
void blk_free(BLOCK *blk)
|
|
BLOCK *blkrealloc(BLOCK *blk, int newlen, int newchunk)
|
|
void blktrunc(BLOCK *blk)
|
|
BLOCK *blk_copy(BLOCK *blk)
|
|
int blk_cmp(BLOCK *a, BLOCK *b)
|
|
void blk_print(BLOCK *blk)
|
|
void nblock_print(NBLOCK *nblk)
|
|
NBLOCK *reallocnblock(int id, int len, int chunk)
|
|
NBLOCK *createnblock(char *name, int len, int chunk)
|
|
int findnblockid(char * name)
|
|
int removenblock(int id)
|
|
int countnblocks(void)
|
|
void shownblocks(void)
|
|
NBLOCK *findnblock(int id)
|
|
BLOCK *copyrealloc(BLOCK *blk, int newlen, int newchunk)
|
|
|
|
SEE ALSO
|
|
blocks, blkfree
|
|
|
|
## Copyright (C) 1999-2006 Landon Curt Noll
|
|
##
|
|
## Calc is open software; you can redistribute it and/or modify it under
|
|
## the terms of the version 2.1 of the GNU Lesser General Public License
|
|
## as published by the Free Software Foundation.
|
|
##
|
|
## Calc is distributed in the hope that it will be useful, but WITHOUT
|
|
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|
|
## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
|
|
## Public License for more details.
|
|
##
|
|
## A copy of version 2.1 of the GNU Lesser General Public License is
|
|
## distributed with calc under the filename COPYING-LGPL. You should have
|
|
## received a copy with calc; if not, write to Free Software Foundation, Inc.
|
|
## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
##
|
|
## Under source code control: 1997/04/05 13:07:13
|
|
## File existed as early as: 1997
|
|
##
|
|
## chongo <was here> /\oo/\ http://www.isthe.com/chongo/
|
|
## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/
|