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. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: blk,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/bin/calc/help/RCS/blk,v $ ## ## Under source code control: 1997/04/05 13:07:13 ## File existed as early as: 1997 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/