iterators.cmod

/* -*- c -*-
|| This file is part of Pike. For copyright information see COPYRIGHT.
|| Pike is distributed under GPL, LGPL and MPL. See the file COPYING
|| for more information.
|| $Id: iterators.cmod,v 1.70 2008/06/29 12:37:10 nilsson Exp $
*/

#include "global.h"
#include "main.h"
#include "object.h"
#include "mapping.h"
#include "multiset.h"
#include "svalue.h"
#include "array.h"
#include "pike_macros.h"
#include "pike_error.h"
#include "pike_memory.h"
#include "dynamic_buffer.h"
#include "interpret.h"
#include "las.h"
#include "gc.h"
#include "stralloc.h"
#include "pike_security.h"
#include "opcodes.h"
#include "pike_error.h"
#include "program.h"
#include "operators.h"
#include "builtin_functions.h"
#include "constants.h"

#define sp Pike_sp

DECLARATIONS

/*! @class Iterator
 *!
 *! This is the interface for iterator objects. They implement an
 *! interface to a collection or stream of data items and a cursor
 *! that can be used to iterate over and examine individual items in
 *! the data set.
 *!
 *! Iterators are typically created to access a data set in some
 *! specific object, array, mapping, multiset or string. An object can
 *! have several iterators that access different data sets in it, or
 *! the same in different ways. E.g. strings have both an iterator for
 *! access char-by-char (@[String.Iterator]), and another for access
 *! over splitted substrings (@[String.SplitIterator]).
 *! @[lfun::_get_iterator] may be defined in an object to get an
 *! instance of the canonical iterator type for it. It's used by e.g.
 *! @[foreach] to iterate over objects conveniently.
 *!
 *! It's not an error to advance an iterator past the beginning or end
 *! of the data set; @[`!()] will only return true then, and @[index]
 *! and @[value] will return @[UNDEFINED]. An iterator in that state
 *! need not keep track of positions, so it's undefined what happens
 *! if it's "moved back" into the set of items.
 *!
 *! Backward movement for iterators is optional. It's supported if and
 *! only if @[`-()] is defined, but even then it's undefined how far
 *! back the iterator can move. Therefore iterators may support only a
 *! limited amount of backward movement, e.g. when they access a
 *! stream through a limited buffer. If such an iterator is moved back
 *! past the limit then it'll behave as if it's pointing entirely
 *! outside the data set (see above).
 *!
 *! An iterator that doesn't support backward movement at all should
 *! throw an error if it's attempted.
 *!
 *! @seealso
 *!   @[predef::get_iterator], @[lfun::_get_iterator],