Functions for operating on generic lists. Provides functiosn for indexing lists, changing list structure, and constructing lists by rearranging or modifying another list.

To use, add the following lines to the beginning of your file:

include <BOSL2/std.scad>

Terminology:

1. Section: List Query Operations

   • is_homogeneous() – Returns true if all members of a list are of the same type.
   • min_length() – Given a list of sublists, returns the length of the shortest sublist.
   • max_length() – Given a list of sublists, returns the length of the longest sublist.
   • list_shape() – Returns the dimensions of an array.
   • in_list() – Returns true if a value is in a list.

2. Section: List Indexing

   • select() – Returns one or more items from a list, with wrapping.
   • slice() – Returns part of a list without wrapping.
   • last() – Returns the last item of a list.
   • list_head() – Returns the elements at the beginning of a list.
   • list_tail() – Returns the elements at the end of a list.
   • bselect() – Select list items using boolean index list.

3. Section: List Construction

   • repeat() – Returns a list of repeated copies of a value.
   • list_bset() – Returns a list where values are spread to locations indicated by a boolean index list.
   • list() – Expands a range into a full list.
   • force_list() – Coerces non-list values into a list.

4. Section: List Modification

   • reverse() – Reverses the elements of a list.
   • list_rotate() – Rotates the ordering of a list.
   • shuffle() – Randomizes the order of a list.
   • repeat_entries() – Repeats list entries (as uniformly as possible) to make list of specified length.
   • list_pad() – Extend list to specified length.
   • list_set() – Sets the value of specific list items.
   • list_insert() – Inserts values into the middle of a list.
   • list_remove() – Removes items by index from a list.
   • list_remove_values() – Removes items by value from a list.

5. Section: List Iteration Index Helper

   • idx() – Returns a range useful for iterating over a list.

6. Section: Lists of Subsets

   • pair() – Returns a list of overlapping consecutive pairs in a list.
   • triplet() – Returns a list of overlapping consecutive triplets in a list.
   • combinations() – Returns a list of all combinations of the list entries.
   • permutations() – Returns a list of all permutations of the list entries.

7. Section: Changing List Structure

   • list_to_matrix() – Groups items in a list into sublists.
   • flatten() – Flattens a list of sublists into a single list.
   • full_flatten() – Recursively flattens nested sublists into a single list of non-list values.

8. Section: Set Manipulation

   • set_union() – Merges two lists, returning a list of unique items.
   • set_difference() – Returns a list of unique items that are in list A, but not in list B.
   • set_intersection() – Returns a list of unique items that are in both given lists.

Alias: is_homogenous()

Synopsis: Returns true if all members of a list are of the same type.

Topics: List Handling, Type Checking

See Also: is_vector(), is_matrix()

Usage:

• bool = is_homogeneous(list, [depth]);

Description:

Returns true when the list has elements of same type up to the depth depth. Booleans and numbers are not distinguinshed as of distinct types.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = is_homogeneous([[1,["a"]], [2,["b"]]]);     // Returns true
b = is_homogeneous([[1,["a"]], [2,[true]]]);    // Returns false
c = is_homogeneous([[1,["a"]], [2,[true]]], 1); // Returns true
d = is_homogeneous([[1,["a"]], [2,[true]]], 2); // Returns false
e = is_homogeneous([[1,["a"]], [true,["b"]]]);  // Returns true

Synopsis: Given a list of sublists, returns the length of the shortest sublist.

Topics: List Handling

See Also: max_length()

Usage:

• llen = min_length(list);

Description:

Returns the length of the shortest sublist in a list of lists.

Arguments:

Example 1:

include <BOSL2/std.scad>
slen = min_length([[3,4,5],[6,7,8,9]]);  // Returns: 3

Synopsis: Given a list of sublists, returns the length of the longest sublist.

Topics: List Handling

See Also: min_length()

Usage:

• llen = max_length(list);

Description:

Returns the length of the longest sublist in a list of lists.

Arguments:

Example 1:

include <BOSL2/std.scad>
llen = max_length([[3,4,5],[6,7,8,9]]);  // Returns: 4

Synopsis: Returns the dimensions of an array.

Topics: Matrices, List Handling

See Also: is_homogeneous()

Usage:

• dims = list_shape(v, [depth]);

Description:

Returns the size of a multi-dimensional array, a list of the lengths at each depth. If the returned value has dims[i] = j then it means the ith index ranges of j items. The return dims[0] is equal to the length of v. Then dims[1] is equal to the length of the lists in v, and in general, dims[i] is equal to the length of the items nested to depth i in the list v. If the length of items at that depth is inconsistent, then undef is returned. If no items exist at that depth then 0 is returned. Note that for simple vectors or matrices it is faster to compute len(v) and len(v[0]).

Arguments:

Example 1:

include <BOSL2/std.scad>
a = list_shape([[[1,2,3],[4,5,6]],[[7,8,9],[10,11,12]]]);     // Returns [2,2,3]
b = list_shape([[[1,2,3],[4,5,6]],[[7,8,9],[10,11,12]]], 0);  // Returns 2
c = list_shape([[[1,2,3],[4,5,6]],[[7,8,9],[10,11,12]]], 2);  // Returns 3
d = list_shape([[[1,2,3],[4,5,6]],[[7,8,9]]]);                // Returns [2,undef,3]

Synopsis: Returns true if a value is in a list.

Topics: List Handling

See Also: select(), slice()

Usage:

• bool = in_list(val, list, [idx]);

Description:

Returns true if value val is in list list. When val==NAN the answer will be false for any list.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = in_list("bar", ["foo", "bar", "baz"]);  // Returns true.
b = in_list("bee", ["foo", "bar", "baz"]);  // Returns false.
c = in_list("bar", [[2,"foo"], [4,"bar"], [3,"baz"]], idx=1);  // Returns true.

Synopsis: Returns one or more items from a list, with wrapping.

Topics: List Handling

See Also: slice(), column(), last()

Usage:

• item = select(list, start);
• item = select(list, [s:d:e]);
• item = select(list, [i0,i1...,ik]);
• list = select(list, start, end);

Description:

Returns a portion of a list, wrapping around past the beginning, if end<start. The first item is index 0. Negative indexes are counted back from the end. The last item is -1. If only the start index is given, returns just the value at that position when start is a number or the selected list of entries when start is a list of indices or a range.

Arguments:

Example 1:

include <BOSL2/std.scad>
l = [3,4,5,6,7,8,9];
a = select(l, 5, 6);   // Returns [8,9]
b = select(l, 5, 8);   // Returns [8,9,3,4]
c = select(l, 5, 2);   // Returns [8,9,3,4,5]
d = select(l, -3, -1); // Returns [7,8,9]
e = select(l, 3, 3);   // Returns [6]
f = select(l, 4);      // Returns 7
g = select(l, -2);     // Returns 8
h = select(l, [1:3]);  // Returns [4,5,6]
i = select(l, [3,1]);  // Returns [6,4]

Synopsis: Returns part of a list without wrapping.

Topics: List Handling

See Also: select(), column(), last()

Usage:

• list = slice(list, s, e);

Description:

Returns a slice of a list, from the first position s up to and including the last position e. The first item in the list is at index 0. Negative indexes are counted back from the end, with -1 referring to the last list item. If s is after e then the empty list is returned. If an index is off the start/end of the list it will refer to the list start/end.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = slice([3,4,5,6,7,8,9], 3, 5);   // Returns [6,7,8]
b = slice([3,4,5,6,7,8,9], 2, -1);  // Returns [5,6,7,8,9]
c = slice([3,4,5,6,7,8,9], 1, 1);   // Returns [4]
d = slice([3,4,5,6,7,8,9], 5);      // Returns [8,9]
e = slice([3,4,5,6,7,8,9], 2, -2);  // Returns [5,6,7,8]
f = slice([3,4,5,6,7,8,9], 4, 3;    // Returns []
g = slice([3,4,5], 1, 5;            // Returns [4,5]
h = slice([3,4,5], 5, 7);           // Returns []

Synopsis: Returns the last item of a list.

Topics: List Handling

See Also: select(), slice(), column()

Usage:

• item = last(list);

Description:

Returns the last element of a list, or undef if empty.

Arguments:

Example 1:

include <BOSL2/std.scad>
l = [3,4,5,6,7,8,9];
x = last(l);  // Returns 9.

Synopsis: Returns the elements at the beginning of a list.

Topics: List Handling

See Also: select(), slice(), list_tail(), last()

Usage:

• list = list_head(list, [to]);

Description:

Returns the head of the given list, from the first item up until the to index, inclusive. By default returns all but the last element of the list. If the to index is negative, then the length of the list is added to it, such that -1 is the last list item. -2 is the second from last. -3 is third from last, etc. If the list is shorter than the given index, then the full list is returned.

Arguments:

Example 1:

include <BOSL2/std.scad>
hlist1 = list_head(["foo", "bar", "baz"]);  // Returns: ["foo", "bar"]
hlist2 = list_head(["foo", "bar", "baz"], -3); // Returns: ["foo"]
hlist3 = list_head(["foo", "bar", "baz"], 2);  // Returns: ["foo","bar"]
hlist4 = list_head(["foo", "bar", "baz"], -5); // Returns: []
hlist5 = list_head(["foo", "bar", "baz"], 5);  // Returns: ["foo","bar","baz"]

Synopsis: Returns the elements at the end of a list.

Topics: List Handling

See Also: select(), slice(), last()

Usage:

• list = list_tail(list, [from]);

Description:

Returns the tail of the given list, from the from index up until the end of the list, inclusive. By default returns all but the first item. If the from index is negative, then the length of the list is added to it, such that -1 is the last list item. -2 is the second from last. -3 is third from last, etc. If you want it to return the last three items of the list, use from=-3.

Arguments:

Example 1:

include <BOSL2/std.scad>
tlist1 = list_tail(["foo", "bar", "baz"]);  // Returns: ["bar", "baz"]
tlist2 = list_tail(["foo", "bar", "baz"], -1); // Returns: ["baz"]
tlist3 = list_tail(["foo", "bar", "baz"], 2);  // Returns: ["baz"]
tlist4 = list_tail(["foo", "bar", "baz"], -5); // Returns: ["foo","bar","baz"]
tlist5 = list_tail(["foo", "bar", "baz"], 5);  // Returns: []

Synopsis: Select list items using boolean index list.

Topics: List Handling

See Also: list_bset()

Usage:

• sublist = bselect(list, index);

Description:

Returns the items in list whose matching element in index evaluates as true.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = bselect([3,4,5,6,7], [false,true,true,false,true]);  // Returns: [4,5,7]

Synopsis: Returns a list of repeated copies of a value.

Topics: List Handling

See Also: count(), lerpn()

Usage:

• list = repeat(val, n);

Description:

Generates a list of n copies of the given value val. If the count n is given as a list of counts, then this creates a multi-dimensional array, filled with val. If n is negative, returns the empty list.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = repeat(1, 4);        // Returns [1,1,1,1]
b = repeat(8, [2,3]);    // Returns [[8,8,8], [8,8,8]]
c = repeat(0, [2,2,3]);  // Returns [[[0,0,0],[0,0,0]], [[0,0,0],[0,0,0]]]
d = repeat([1,2,3],3);   // Returns [[1,2,3], [1,2,3], [1,2,3]]
e = repeat(4, -1);       // Returns []

Synopsis: Returns a list where values are spread to locations indicated by a boolean index list.

Topics: List Handling

See Also: bselect()

Usage:

• arr = list_bset(indexset, valuelist, [dflt]);

Description:

Opposite of bselect(). Returns a list the same length as indexlist, where each item will either be 0 if the corresponding item in indexset is false, or the next sequential value from valuelist if the item is true. The number of true values in indexset must be equal to the length of valuelist.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = list_bset([false,true,false,true,false], [3,4]);  // Returns: [0,3,0,4,0]
b = list_bset([false,true,false,true,false], [3,4], dflt=1);  // Returns: [1,3,1,4,1]

Synopsis: Expands a range into a full list.

Topics: List Handling, Type Conversion

See Also: scalar_vec3(), force_list()

Usage:

• list = list(l)

Description:

Expands a range into a full list. If given a list, returns it verbatim. If given a string, explodes it into a list of single letters.

Arguments:

Example 1:

include <BOSL2/std.scad>
l1 = list([3:2:9]);  // Returns: [3,5,7,9]
l2 = list([3,4,5]);  // Returns: [3,4,5]
l3 = list("Foo");    // Returns: ["F","o","o"]
l4 = list(23);       // Returns: [23]

Synopsis: Coerces non-list values into a list.

Topics: List Handling

See Also: scalar_vec3()

Usage:

• list = force_list(value, [n], [fill]);

Description:

Coerces non-list values into a list. Makes it easy to treat a scalar input consistently as a singleton list, as well as list inputs.

• If value is a list, then that list is returned verbatim.
• If value is not a list, and fill is not given, then a list of n copies of value will be returned.
• If value is not a list, and fill is given, then a list n items long will be returned where value will be the first item, and the rest will contain the value of fill.

Arguments:

Example 1:

include <BOSL2/std.scad>
x = force_list([3,4,5]);  // Returns: [3,4,5]
y = force_list(5);  // Returns: [5]
z = force_list(7, n=3);  // Returns: [7,7,7]
w = force_list(4, n=3, fill=1);  // Returns: [4,1,1]

Synopsis: Reverses the elements of a list.

Topics: List Handling

See Also: select(), list_rotate()

Usage:

• rlist = reverse(list);

Description:

Reverses a list or string.

Arguments:

Example 1:

include <BOSL2/std.scad>
reverse([3,4,5,6]);  // Returns [6,5,4,3]

Synopsis: Rotates the ordering of a list.

Topics: List Handling

See Also: select(), reverse()

Usage:

• rlist = list_rotate(list, [n]);

Description:

Rotates the contents of a list by n positions left, so that list[n] becomes the first entry of the list. If n is negative, then the rotation is abs(n) positions to the right. If list is a string, then a string is returned with the characters rotates within the string.

Arguments:

Example 1:

include <BOSL2/std.scad>
l1 = list_rotate([1,2,3,4,5],-2); // Returns: [4,5,1,2,3]
l2 = list_rotate([1,2,3,4,5],-1); // Returns: [5,1,2,3,4]
l3 = list_rotate([1,2,3,4,5],0);  // Returns: [1,2,3,4,5]
l4 = list_rotate([1,2,3,4,5],1);  // Returns: [2,3,4,5,1]
l5 = list_rotate([1,2,3,4,5],2);  // Returns: [3,4,5,1,2]
l6 = list_rotate([1,2,3,4,5],3);  // Returns: [4,5,1,2,3]
l7 = list_rotate([1,2,3,4,5],4);  // Returns: [5,1,2,3,4]
l8 = list_rotate([1,2,3,4,5],5);  // Returns: [1,2,3,4,5]
l9 = list_rotate([1,2,3,4,5],6);  // Returns: [2,3,4,5,1]

Synopsis: Randomizes the order of a list.

Topics: List Handling

See Also: sort(), sortidx(), unique(), unique_count()

Usage:

• shuffled = shuffle(list, [seed]);

Description:

Shuffles the input list into random order. If given a string, shuffles the characters within the string. If you give a numeric seed value then the permutation will be repeatable.

Arguments:

Example 1:

include <BOSL2/std.scad>
//        Spades   Hearts    Diamonds  Clubs
suits = ["\u2660", "\u2661", "\u2662", "\u2663"];
ranks = [2,3,4,5,6,7,8,9,10,"J","Q","K","A"];
cards = [for (suit=suits, rank=ranks) str(rank,suit)];
deck = shuffle(cards);

Synopsis: Repeats list entries (as uniformly as possible) to make list of specified length.

Topics: List Handling

See Also: repeat()

Usage:

• newlist = repeat_entries(list, N, [exact]);

Description:

Takes a list as input and duplicates some of its entries to produce a list with length N. If the requested N is not a multiple of the list length then the entries will be duplicated as uniformly as possible. You can also set N to a vector, in which case len(N) must equal len(list) and the output repeats the ith entry N[i] times. In either case, the result will be a list of length N. The exact option requires that the final length is exactly as requested. If you set it to false then the algorithm will favor uniformity and the output list may have a different number of entries due to rounding.

When applied to a path the output path is the same geometrical shape but has some vertices repeated. This can be useful when you need to align paths with a different number of points. (See also subdivide_path for a different way to do that.)

Arguments:

Example 1:

include <BOSL2/std.scad>
list = [0,1,2,3];
a = repeat_entries(list, 6);  // Returns: [0,0,1,2,2,3]
b = repeat_entries(list, 6, exact=false);  // Returns: [0,0,1,1,2,2,3,3]
c = repeat_entries(list, [1,1,2,1], exact=false);  // Returns: [0,1,2,2,3]

Synopsis: Extend list to specified length.

Topics: List Handling

See Also: force_list(), scalar_vec3()

Usage:

• newlist = list_pad(list, minlen, [fill]);

Description:

If the list list is shorter than minlen length, pad it to length with the value given in fill.

Arguments:

Example 1:

include <BOSL2/std.scad>
list = [3,4,5];
nlist = list_pad(list,5,23);  // Returns: [3,4,5,23,23]

Synopsis: Sets the value of specific list items.

Topics: List Handling

See Also: list_insert(), list_remove(), list_remove_values()

Usage:

• list = list_set(list, indices, values, [dflt], [minlen]);

Description:

Takes the input list and returns a new list such that list[indices[i]] = values[i] for all of the (index,value) pairs supplied and unchanged for other indices. If you supply indices that are larger that the length of the list then the list is extended and filled in with the dflt value. If you specify indices smaller than zero then they index from the end, with -1 being the last element. Negative indexing does not wrap around: an error occurs if you give a value smaller than -len(list). If you set minlen then the list is lengthed, if necessary, by padding with dflt to that length. Repetitions in indices are not allowed. The lists indices and values must have the same length. If indices is given as a scalar, then that index of the given list will be set to the scalar value of values.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = list_set([2,3,4,5], 2, 21);  // Returns: [2,3,21,5]
b = list_set([2,3,4,5], [1,3], [81,47]);  // Returns: [2,81,4,47]

Synopsis: Inserts values into the middle of a list.

Topics: List Handling

See Also: list_set(), list_remove(), list_remove_values()

Usage:

• list = list_insert(list, indices, values);

Description:

Insert values into list before position indices. The indices for insertion are based on the original list, before any insertions have occurred. You can use negative indices to count from the end of the list. Note that -1 refers to the last element, so the insertion will be before the last element.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = list_insert([3,6,9,12],1,5);  // Returns [3,5,6,9,12]
b = list_insert([3,6,9,12],[1,3],[5,11]);  // Returns [3,5,6,9,11,12]

Synopsis: Removes items by index from a list.

Topics: List Handling

See Also: list_set(), list_insert(), list_remove_values()

Usage:

• list = list_remove(list, ind);

Description:

If ind is a number remove list[ind] from the list. If ind is a list of indices remove from the list the item all items whose indices appear in ind. If you give indices that are not in the list they are ignored.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = list_remove([3,6,9,12],1);      // Returns: [3,9,12]
b = list_remove([3,6,9,12],[1,3]);  // Returns: [3,9]
c = list_remove([3,6],3);           // Returns: [3,6]

Synopsis: Removes items by value from a list.

Topics: List Handling

See Also: list_set(), list_insert(), list_remove()

Usage:

• list = list_remove_values(list, values, [all]);

Description:

Removes the first, or all instances of the given value or list of values from the list. If you specify all=false and list a value twice then the first two instances will be removed. Note that if you want to remove a list value such as [3,4] then you must give it as a singleton list, or it will be interpreted as a list of two scalars to remove.

Arguments:

Example 1:

include <BOSL2/std.scad>
test = [3,4,[5,6],7,5,[5,6],4,[6,5],7,[4,4]];
a=list_remove_values(test,4); // Returns: [3, [5, 6], 7, 5, [5, 6], 4, [6, 5], 7, [4, 4]]
b=list_remove_values(test,[4,4]); // Returns: [3, [5, 6], 7, 5, [5, 6], [6, 5], 7, [4, 4]]
c=list_remove_values(test,[4,7]); // Returns: [3, [5, 6], 5, [5, 6], 4, [6, 5], 7, [4, 4]]
d=list_remove_values(test,[5,6]); // Returns: [3, 4, [5, 6], 7, [5, 6], 4, [6, 5], 7, [4, 4]]
e=list_remove_values(test,[[5,6]]); // Returns: [3,4,7,5,[5,6],4,[6,5],7,[4,4]]
f=list_remove_values(test,[[5,6]],all=true); // Returns: [3,4,7,5,4,[6,5],7,[4,4]]
animals = ["bat", "cat", "rat", "dog", "bat", "rat"];
animals2 = list_remove_values(animals, "rat");   // Returns: ["bat","cat","dog","bat","rat"]
nonflying = list_remove_values(animals, "bat", all=true);  // Returns: ["cat","rat","dog","rat"]
animals3 = list_remove_values(animals, ["bat","rat"]);  // Returns: ["cat","dog","bat","rat"]
domestic = list_remove_values(animals, ["bat","rat"], all=true);  // Returns: ["cat","dog"]
animals4 = list_remove_values(animals, ["tucan","rat"], all=true);  // Returns: ["bat","cat","dog","bat"]

Synopsis: Returns a range useful for iterating over a list.

Topics: List Handling, Iteration

See Also: count()

Usage:

• range = idx(list, [s=], [e=], [step=]);
• for(i=idx(list, [s=], [e=], [step=])) ...

Description:

Returns the range that gives the indices for a given list. This makes is a little bit easier to loop over a list by index, when you need the index numbers and looping of list values isn't enough. Note that the return is a range not a list.

Arguments:

Example 1:

include <BOSL2/std.scad>
colors = ["red", "green", "blue"];
for (i=idx(colors)) right(20*i) color(colors[i]) circle(d=10);

Synopsis: Returns a list of overlapping consecutive pairs in a list.

Topics: List Handling, Iteration

See Also: idx(), triplet(), combinations(), permutations()

Usage:

• p = pair(list, [wrap]);
• for (p = pair(list, [wrap])) ... // On each iteration, p contains a list of two adjacent items.

Description:

Returns a list of all of the pairs of adjacent items from a list, optionally wrapping back to the front. The pairs overlap, and are returned in order starting with the first two entries in the list. If the list has less than two elements, the empty list is returned.

Arguments:

Example 1: Does NOT wrap from end to start,

include <BOSL2/std.scad>
for (p = pair(circle(d=40, $fn=12)))
    stroke(p, endcap2="arrow2");

Example 2: Wraps around from end to start.

include <BOSL2/std.scad>
for (p = pair(circle(d=40, $fn=12), wrap=true))
    stroke(p, endcap2="arrow2");

Example 3:

include <BOSL2/std.scad>
l = ["A","B","C","D"];
echo([for (p=pair(l)) str(p.y,p.x)]);  // Outputs: ["BA", "CB", "DC"]

Synopsis: Returns a list of overlapping consecutive triplets in a list.

Topics: List Handling, Iteration

See Also: idx(), pair(), combinations(), permutations()

Usage:

• list = triplet(list, [wrap]);
• for (t = triplet(list, [wrap])) ...

Description:

Returns a list of all adjacent triplets from a list, optionally wrapping back to the front. If you set wrap to true then the first triplet is the one centered on the first list element, so it includes the last element and the first two elements. If the list has fewer than three elements then the empty list is returned.

Arguments:

Example 1:

include <BOSL2/std.scad>
list = [0,1,2,3,4];
a = triplet(list);               // Returns [[0,1,2],[1,2,3],[2,3,4]]
b = triplet(list,wrap=true);     // Returns [[4,0,1],[0,1,2],[1,2,3],[2,3,4],[3,4,0]]
letters = ["A","B","C","D","E"];
[for (p=triplet(letters)) str(p.z,p.y,p.x)];     // Returns: ["CBA", "DCB", "EDC"]

Example 2:

include <BOSL2/std.scad>
path = [for (i=[0:24]) polar_to_xy(i*2, i*360/12)];
for (t = triplet(path)) {
    a = t[0]; b = t[1]; c = t[2];
    v = unit(unit(a-b) + unit(c-b));
    translate(b) rot(from=FWD,to=v) anchor_arrow2d();
}
stroke(path);

Synopsis: Returns a list of all combinations of the list entries.

Topics: List Handling, Iteration

See Also: idx(), pair(), triplet(), permutations()

Usage:

• list = combinations(l, [n]);

Description:

Returns a list of all of the (unordered) combinations of n items out of the given list l. For the list [1,2,3,4], with n=2, this will return [[1,2], [1,3], [1,4], [2,3], [2,4], [3,4]]. For the list [1,2,3,4], with n=3, this will return [[1,2,3], [1,2,4], [1,3,4], [2,3,4]].

Arguments:

Example 1:

include <BOSL2/std.scad>
pairs = combinations([3,4,5,6]);  // Returns: [[3,4],[3,5],[3,6],[4,5],[4,6],[5,6]]
triplets = combinations([3,4,5,6],n=3);  // Returns: [[3,4,5],[3,4,6],[3,5,6],[4,5,6]]

Example 2:

include <BOSL2/std.scad>
for (p=combinations(regular_ngon(n=7,d=100))) stroke(p);

Synopsis: Returns a list of all permutations of the list entries.

Topics: List Handling, Iteration

See Also: idx(), pair(), triplet(), combinations()

Usage:

• list = permutations(l, [n]);

Description:

Returns a list of all of the (ordered) permutation n items out of the given list l. For the list [1,2,3], with n=2, this will return [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]] For the list [1,2,3], with n=3, this will return [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]

Arguments:

Example 1:

include <BOSL2/std.scad>
pairs = permutations([3,4,5,6]);  // // Returns: [[3,4],[3,5],[3,6],[4,3],[4,5],[4,6],[5,3],[5,4],[5,6],[6,3],[6,4],[6,5]]

Synopsis: Groups items in a list into sublists.

Topics: Matrices, List Handling

See Also: column(), submatrix(), hstack(), flatten(), full_flatten()

Usage:

• groups = list_to_matrix(v, cnt, [dflt]);

Description:

Takes a flat list of values, and groups items in sets of cnt length. The opposite of this is flatten().

Arguments:

Example 1:

include <BOSL2/std.scad>
v = [1,2,3,4,5,6];
a = list_to_matrix(v,2)  // returns [[1,2], [3,4], [5,6]]
b = list_to_matrix(v,3)  // returns [[1,2,3], [4,5,6]]
c = list_to_matrix(v,4,0)  // returns [[1,2,3,4], [5,6,0,0]]

Synopsis: Flattens a list of sublists into a single list.

Topics: Matrices, List Handling

See Also: column(), submatrix(), hstack(), full_flatten()

Usage:

• list = flatten(l);

Description:

Takes a list of lists and flattens it by one level.

Arguments:

Example 1:

include <BOSL2/std.scad>
l = flatten([[1,2,3], [4,5,[6,7,8]]]);  // returns [1,2,3,4,5,[6,7,8]]

Synopsis: Recursively flattens nested sublists into a single list of non-list values.

Topics: Matrices, List Handling

See Also: column(), submatrix(), hstack(), flatten()

Usage:

• list = full_flatten(l);

Description:

Collects in a list all elements recursively found in any level of the given list. The output list is ordered in depth first order.

Arguments:

Example 1:

include <BOSL2/std.scad>
l = full_flatten([[1,2,3], [4,5,[6,7,8]]]);  // returns [1,2,3,4,5,6,7,8]

Synopsis: Merges two lists, returning a list of unique items.

Topics: Set Handling, List Handling

See Also: set_difference(), set_intersection()

Usage:

• s = set_union(a, b, [get_indices]);

Description:

Given two sets (lists with unique items), returns the set of unique items that are in either a or b. If get_indices is true, a list of indices into the new union set are returned for each item in b, in addition to returning the new union set. In this case, a 2-item list is returned, [INDICES, NEWSET], where INDICES is the list of indices for items in b, and NEWSET is the new union set.

Arguments:

Example 1:

include <BOSL2/std.scad>
set_a = [2,3,5,7,11];
set_b = [1,2,3,5,8];
set_u = set_union(set_a, set_b);
// set_u now equals [2,3,5,7,11,1,8]
set_v = set_union(set_a, set_b, get_indices=true);
// set_v now equals [[5,0,1,2,6], [2,3,5,7,11,1,8]]

Synopsis: Returns a list of unique items that are in list A, but not in list B.

Topics: Set Handling, List Handling

See Also: set_union(), set_intersection()

Usage:

• s = set_difference(a, b);

Description:

Given two sets (lists with unique items), returns the set of items that are in a, but not b.

Arguments:

Example 1:

include <BOSL2/std.scad>
set_a = [2,3,5,7,11];
set_b = [1,2,3,5,8];
set_d = set_difference(set_a, set_b);
// set_d now equals [7,11]

Synopsis: Returns a list of unique items that are in both given lists.

Topics: Set Handling, List Handling

See Also: set_union(), set_difference()

Usage:

• s = set_intersection(a, b);

Description:

Given two sets (lists with unique items), returns the set of items that are in both sets.

Arguments:

Example 1:

include <BOSL2/std.scad>
set_a = [2,3,5,7,11];
set_b = [1,2,3,5,8];
set_i = set_intersection(set_a, set_b);
// set_i now equals [2,3,5]