vector.h | documentation |
#charset "us-ascii" #pragma once /* * Copyright (c) 2000, 2006 Michael J. Roberts * * This file is part of TADS 3. * * This header defines the Vector intrinsic class. */ /* include our base class definition */ #include "systype.h" /* * The Vector intrinsic class provides a varying-length array type. * Vectors can be expanded dynamically, and values within a vector can be * changed. (In contrast, List is a constant type: a value within a list * cannot be changed, and new values can't be added to a list. Any * manipulation of a List results in a new, separate List object, leaving * the original unchanged. Vector allows new values to be added and * existing values to be changed in place, without creating a new object.) */ intrinsic class Vector 'vector/030005': Collection { /* * Create a list with the same elements as the vector. If 'start' is * specified, it's the index of the first element we store; we'll * store elements starting at index 'start'. If 'cnt' is specified, * it gives the maximum number of elements for the new list; by * default, we'll store all of the elements from 'start' to the last * element. */ toList(start?, cnt?); /* get the number of elements in the vector */ length(); /* * Copy from another vector or list. Elements are copied from the * source vector or list starting at the element given by 'src_start', * and are copied into 'self' starting at the index given by * 'dst_start'. At most 'cnt' values are copied, but we stop when we * reach the last element of either the source or destination values. * If either index is negative, it counts from the end of the vector: * -1 is the last element, -2 is the second to last, and so on. */ copyFrom(src, src_start, dst_start, cnt); /* * Fill with a given value, starting at the given element (the first * element if not specified), and running for the given number of * elements (the remaining existing elements of the vector, if not * specified). The vector is expanded if necessary. A negative * starting index counts backwards from the last element. */ fillValue(val, start?, cnt?); /* * Select a subset of the vector. Returns a new vector consisting * only of the elements of this vector for which the callback function * returns true. */ subset(func); /* * Apply a callback function to each element of the vector. For each * element of the vector, invokes the callback, and replaces the * element with the return value of the callback. Modifies the vector * in-place, and returns 'self'. */ applyAll(func); /* * Find the first element for which the given condition is true. * Apply the callback function (which encodes the condition to * evaluate) to each element in turn, starting with the first. For * each element, if the callback returns nil, proceed to the next * element; otherwise, stop and return the index of the element. If * the callback never returns true for any element, we'll return nil. */ indexWhich(cond); /* * Invoke the callback func(val) on each element, in order from first * to last. No return value. */ forEach(func); /* * Invoke the callback func(index, val) on each element, in order from * first to last. No return value. */ forEachAssoc(func); /* * Apply the callback function to each element of this vector, and * return a new vector consisting of the results. Effectively maps * the vector to a new vector using the given function, leaving the * original vector unchanged. */ mapAll(func); /* get the index of the first match for the given value */ indexOf(val); /* * Find the first element for which the given condition is true, and * return the value of the element. */ valWhich(cond); /* find the last element with the given value, and return its index */ lastIndexOf(val); /* * Find the last element for which the condition is true, and return * the index of the element. Applies the callback to each element in * turn, starting with the last element and working backwards. For * each element, if the callback returns nil, proceeds to the previous * element; otherwise, stops and returns the index of the element. If * the callback never returns true for any element, we'll return nil. */ lastIndexWhich(cond); /* * Find the last element for which the condition is true, and return * the value of the element */ lastValWhich(cond); /* count the number of elements with the given value */ countOf(val); /* count the number of elements for which the callback returns true */ countWhich(cond); /* create a new vector consisting of the unique elements of this vector */ getUnique(); /* * append the elements of the list or vector 'val' to the elements of * this vector, then remove repeated elements in the result; returns a * new vector with the unique elements of the combination */ appendUnique(val); /* * Sort the vector in place; returns 'self'. If the 'descending' * flag is provided and is not nil, we'll sort the vector in * descending order rather than ascending order. * * If the 'comparisonFunction' argument is provided, it must be a * callback function; the callback takes two arguments, and returns * an integer less than zero if the first argument value is less * than the second, zero if they're equal, and an integer greater * than zero if the first is greater than the second. If no * 'comparisonFunction' argument is provided, or it's provided and * its value is nil, we'll simply compare the vector elements as * ordinary values. The comparison function can be provided for * caller-defined orderings, such as ordering a set of objects. */ sort(descending?, comparisonFunction?); /* * Set the length - if this is shorter than the current length, * existing items will be discarded; if it's longer, the newly added * slots will be set to nil. Returns 'self'. */ setLength(newElementCount); /* * Insert one or more elements at the given index. If the starting * index is 1, the elements will be inserted before the first existing * element. If the index is one higher than the number of elements, * the elements will be inserted after all existing elements. A * negative starting index counts from the end of the vector: -1 is the * last element, -2 is the second to last, and so on. A zero starting * index inserts after the last existing element. * * Note that a list value argument will simply be inserted as a single * element. * * Returns 'self'. */ insertAt(startingIndex, val, ...); /* * Delete the element at the given index, reducing the length of the * vector by one element. If 'index' is negative, it counts from the * end of the vector: -1 is the last element, -2 is the second to last, * and so on. Returns 'self'. */ removeElementAt(index); /* * Delete the range of elements starting at startingIndex and ending at * endingIndex. The elements at the ends of the range are included in * the deletion. If startingIndex == endingIndex, only one element is * removed. If either index is negative, it counts backwards from the * last element: -1 is the last element, -2 is the second to last, and * so on. The length of the vector is reduced by the number of * elements removed. Returns 'self'. */ removeRange(startingIndex, endingIndex); /* * Append an element to the vector. This works just like insertAt() * with a starting index one higher than the length of the vector. * This has almost the same effect as the '+' operator, but treats a * list value like any other value by simply inserting the list as a * single new element (rather than appending each item in the list * individually, as the '+' operator would). */ append(val); /* * Prepend an element. This works like insertAt() with a starting * index of 1. */ prepend(val); /* * Append all elements from a list or vector. This works like * append(val), except that if 'val' is a list or vector, the elements * of 'val' will be appended individually, like the '+' operator does. * The difference between this method and the '+' operator is that * this method modifies this Vector by adding the new elements * directly to the existing Vector object, whereas the '+' operator * creates a new Vector to store the result. */ appendAll(val); /* * Remove an element by value. Each element of the vector matching * the given value is removed. The vector is modified in-place. The * return value is 'self'. */ removeElement(val); /* * Splice new values into the vector. Deletes the 'del' elements * starting at 'idx', then inserts the extra arguments in their place. * Updates the vector in place. To insert items without deleting * anything, pass 0 for 'del'. To delete items without inserting * anything, omit any additional arguments. Returns 'self'. */ splice(idx, del, ...); /* * Combine the vector elements into a string. This converts each * element into a string value using the usual default conversions (or * throws an error if string conversion isn't possible), then * concatenates the values together and returns the result. If * 'separator' is provided, it's a string that's interposed between * elements; if this is omitted, the elements are concatenated together * with no extra characters in between. */ join(sep?); /* * Class method: Generate a new Vector. 'func' is a callback function, * which can take zero or one argument. 'n' is the number of elements * for the new list. For each element, 'func' is invoked as func() if * it takes no arguments, or func(idx) if it takes one argument, where * 'idx' is the index of the element being generated. The return value * of the call to 'func' is stored as the list element. The method * returns the resulting list. For example, a vector of the first ten * even positive integers: Vector.generate({i: i*2}, 10). */ static generate(func, n); /* * Get the index of the element with the minimum value. If 'func' is * missing, this simply returns the index of the element with the * smallest value, comparing the element values as though using the '>' * and '<' operators. If 'func' is specified, it must be a function; * it's called as func(x) for each element's value, and the result of * the overall call is the index of the element for which func(x) * returns the smallest value. For example, if you have a vector v * containing string elements, v.indexOfMin({x: x.length()}) returns * the index of the shortest string. */ indexOfMin(func?); /* * Get the minimum element value. If 'func' is missing, this simply * returns the smallest element value. If 'func' is specified, it must * be a function; it's called as func(x) for each element value x, and * the result of the overall method call is the element value x that * minimizes func(x). For example, if v is a vector containing string * elements, v.minVal({x: x.length()}) returns the shortest string. */ minVal(func?); /* * Get the index of the element the maximum value. If 'func' is * missing, this simply returns the index of the element with the * largest value, comparing the element values as though using the '>' * and '<' operators. If 'func' is specified, it must be a function; * it's called as func(x) for each element value x, and the result of * the overall call is the index of the element for which func(x) * returns the greatest value. For example, if you have a vector v * containing string elements, v.indexOfMax({x: x.length()}) returns * the index of the longest string. */ indexOfMax(func?); /* * Get the maximum element value. If 'func' is missing, this returns * the largest element value. If 'func' is specified, it must be a * function; it's called as func(x) for each element value x, and the * result of the overall method call is the element value x that * maximizes func(x). For example, if v is a vector containing string * elements, v.minVal({x: x.length()}) returns the longest string. */ maxVal(func?); }
TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3
Generated on 5/16/2013 from TADS version 3.1.3