Clarion Community Help

Navigation: Language Reference > 3 - Variable Declarations > Data Types >====== ASTRING (atomic string) ======

label	ASTRING([stringtoken])	[,DIM()] [,NAME()] [,EXTERNAL] [,DLL] [,STATIC] [,THREAD]
		[,AUTO] [,PRIVATE] [,PROTECTED]

ASTRING	A reference to a character string.
stringtoken	The initial string token of the ASTRING.
DIM	Dimension the variable as an array.
OVER	The ASTRING reference may share a memory location with another variable.
NAME	Specify an alternate, “external” name for the field.
EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.
DLL	Specify the variable is defined in a .DLL. This is required in addition to the EXTERNAL attribute.
STATIC	Specifies the memory for the ASTRING reference variable is permanently allocated.
THREAD	Specify memory for the variable is allocated once for each execution thread. Also implicitly adds the STATIC attribute on Procedure Local data.
AUTO	Specify the variable has no initial string token.
PRIVATE	Specify the variable is not visible outside the module containing the CLASS methods. Valid only in a CLASS.
PROTECTED	Specify the variable is not visible outside base CLASS and derived CLASS methods. Valid only in a CLASS.

ASTRING (similar to a Win32 ATOM) declares a reference to a variable length string (string token) with a maximum size of 64k. Although the size of the string token may be up to a maximum of 64k, it is recommended for use on smaller strings. The storage space for an ASTRING is allocated dynamically as needed for the lifetime of the procedure in which it is created. However the allocated storage is never deallocated; it is instead reused for subsequent use of the same text values.

ASTRINGs are useful when a lot of the same text is being stored and compared. Each time a new ASTRING is created, an entry is created in a memory table. When an ASTRING is assigned a value that already exists in the table, the ASTRING simply points to the existing ASTRING. This saves memory and makes string comparison very fast.

ASTRINGs are not supported by any of the file drivers.

ASTRINGs may be passed as parameters to procedures by value or by reference. They may also be passed as an untyped value or untyped variable parameters. An ASTRING can be returned from a procedure only as a value.

Proper matching of ASTRING types when used in expressions, procedure parameters,and in queue processing is essential.

Regarding expressions, If one operand of the expression is an ASTRING, the other must also be an ASTRING. If that is not possible, the use of STRING and CSTRING types in expressions is faster and needs far less resources. Every string used as an initial value of ASTRING variables is allocated twice in memory as a minimum.

If the parameter prototype of procedure is declared as ASTRING, the actual parameter receiving the passed value should also be defined as an ASTRING type. Otherwise, the value of the actual parameter is added to the ASTRING's hash table.