NAME

String::TieStack - base class for Rexx-type stacks

SYNOPSIS

 # Set default to no stack limits
 use String::TieStack ;                      

 # Set default so stacks are limited to 400 entries
 use String::TieStack  max_entries => 400 ;  

 # Set default so stacks are limited to 2*1024 bytes
 use String::TieStack  max_KBytes  =>   2 ;  

 $t = tie my @arr , 'String::TieStack';
 push       @arr , qw(  one two )  ;
 unshift    @arr , qw( -one zero ) ;
 pop        @arr                   ;
 $t->queue ( qw( -two -three) ;  # Same like $t->UNSHIFT( reverse @_ )
 $t->pull(3) ;                   # Returns the N  topmost elements
 $t->pullall ;                   # Pop() all entries in one step.
 $t->CLEAR   ;                   # Clears the stack. Same as @arr = ()  ;
 $t->qelem   ;                   # Return the number of entries in the stack
 $t->queued  ;                   # Alias for qelem()
 $t->makebuf ;                   # Create a new buffer 
 $t->qbuf    ;                   # Return the number of buffer in the stack
 $t->dropbuf ;                   # Remove the topmost buffer
 $t->desbuf  ;                   # Remove all buffers 
 pullbuf
 $t->max_entries;                # get/set the value of max_entries 
 $t->max_KBytes ;                # get/set the value of max_KBytes
 limits
 $t->printq  ;                   # Print all entries 
 dumpq
 pdumpq

DESCRIPTION

 This module implements a base class for Rexx-type stacks.

By default, stacks have no entry or size limits; although, defaults can be changed at "use" time (as shown above), or they can be explicitly set by methods after the stack is instantiated. See the LIMIT SECTION for details.

STORE FUNCTIONS

 queue(), PUSH(),

queue()

Same like UNSHIFT( reverse @_ ) ; that is, arguments are (logically) placed into stack as one unshift() call per argument.

PUSH()

Takes multiple arguments and performs a push operation on the stack. If stack limits prevent the operation to push all arguments, non of the arguments will be pushed on the stack. The return value is the number of items of the stack (after the push), and false on failure.

Returns the number of entries in the stack.

RETRIEVE FUNCTIONS

 UNSHIFT(), POP, pull(), pullall(), pullbuf()

UNSHIFT()

Similar the Perl's unshift() operator, but stack limits could prevent the operation to succeed.

POP()

Retrieves the topmost elements. If the element removed is bellow an empty buffer, the buffer is also destroyed.

pull()

Returns the topmost N elements from the stack; it is similar to calling POP() N number of times. N defaults to 1 when the argument is omitted. On failure, it returns undef .

pullall()

Returns all elements of the stack as an array of strings. After this operation, the stack will be empty.

pullbuf ()

 See description in section BUFFER FUNCTION .

MISC FUNCTIONS

 CLEAR(), qelem(), queued()

CLEAR()

Clears all entries from the stack. The stack limits stay the same.

qelem()

Returns the number of entries (elements) in the stack

queued()

An alias for qelem() . Returns the number of entries (elements) on the stack.

BUFFER FUNCTIONS

 makebuf(), qbuf(), dropbuf(), desbuf(), pullbuf()

makebuf()

Creates a buffer on top of the stack. Although elements pushed to the stack will still go on top of the stack, the unshift() and queue() operations will place their elements at the point were there the (last) buffer was created. For example, if the stack had ten elements before makebuf, the push operation will still place its arguments at the very top, but the unshift() and queue() operators will think that the bottom of the stack is just after the 10th item, and will place their arguments on top of the 10th item since it now thinks thinks the bottom has moved.

On success, this function returns the number of buffers on the stack (including this latest one). On failure it returns undef, this can happen if we try to create the same buffer twice at the same point.

qbuf()

Returns the number of buffers on the stack.

dropbuf()

Removes the topmost buffer (and its elements) from the stack.

desbuf()

Removes all buffers (and their elements) from the stack. The stack could still contain elements that were not in any buffer.

pullbuf()

Returns all elements of the topmost buffer as an array of strings. After this operation the topmost buffer will be empty. Returns undef on failure, when the stack has no buffers.

LIMIT FUNCTIONS

 max_entries(), max_KBytes(), limits()

max_entries()

When called with an integer argument, it sets the max_entries limit for the stack to that value. The stack remains the same, it will not remove old entries if the new limit is lower. The return value is the value of max_entries after the update. When called without an argument, it returns the current value of max_entries. So, the return value is the same for both calls.

If max_entries is set to 0 (the default), it means that there are no limits based on the number entries -- the number of entries is unlimited.

max_KBytes()

When called with an integer or float argument, it sets the max_KBytes limit for the stack to that value. The stack remains the same, it will not remove old entries if the the new limit is lower. The argument should be in Kilo-Byte units, where 1KB = 1024 Bytes . Therefore, if you want the stack to contain entries that together total no more than 10 bytes, call it as max_KBytes(.01);

limits()

It is a get/set function that reads or initializes the values of max_entries and max_KBytes. When called with no arguments, it returns an array of two values; and when called with two arguments it sets max_entries and max_Kbytes.

PRINT FUNCTIONS

 dumpq(), pdumpq(), printq()

dumpq()

Returns the stringified data structure of the Perl stack object

pdumpq()

Prints to stdout the stringified data structure of the Perl stack object

printq()

Prints to stdout all elements of the stack. (The stack is not changed.)

EXPORT

None, and not needed.

AUTHOR

Ioannis Tambouras, <ioannis@earthlink.net>

SEE ALSO

String::RexxStack, regina