Module: sage.structure.sequence
Sequences
A mutable sequence of elements with a common guaranteed category, which can be set immutable.
Sequence derives from list, so have all the functionality of lists and
can be used wherever lists are used. When a sequence is created
without explicitly given the common universe of the elements, the
constructor coerces the first and second element to come
canonical common parent, if possible, then the second and
third, etc.. If this is possible, it then coerces everything into the
canonical parent at the end. (Note that canonical coercion is very
restrictive.) The sequence then has a function universe()
which returns either the common canonical parent (if the coercion
succeeded), or the category of all objects (Objects()). So if you
have a list
and type
sage: v = [1, 2/3, 5] sage: w = Sequence(v) sage: w.universe() Rational Field
then since w.universe()
is
then you're guaranteed that all
elements of
are rationals:
sage: v[0].parent() Integer Ring sage: w[0].parent() Rational Field
If you do assignment to
this property of being rationals is guaranteed
to be preserved.
sage: w[0] = 2 sage: w[0].parent() Rational Field sage: w[0] = 'hi' Traceback (most recent call last): ... TypeError: unable to convert hi to a rational
However, if you do w = Sequence(v)
and the resulting universe
is Objects()
, the elements are not guaranteed to have any
special parent. This is what should happen, e.g., with finite field
elements of different characteristics:
sage: v = Sequence([GF(3)(1), GF(7)(1)]) sage: v.universe() Category of objects
You can make a list immutable with v.freeze()
. Assignment is
never again allowed on an immutable list.
Creation of a sequence involves making a copy of the input list, and substantial coercions. It can be greatly sped up by explicitly specifying the universe of the sequence:
sage: v = Sequence(range(10000), universe=ZZ)
Class: seq
A universe is either an object that supports coercion (e.g., a parent), or a category.
Input:
sage: v = Sequence(range(10)) sage: v.universe() <type 'int'> sage: v [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
You can also use seq for "Sequence", which is identical to using Sequence:
sage: v = seq([1,2,1/1]); v [1, 2, 1] sage: v.universe() Rational Field sage: v.parent() Category of sequences in Rational Field sage: v.parent()([3,4/3]) [3, 4/3]
Note that assignment coerces if possible,
sage: v = Sequence(range(10), ZZ) sage: a = QQ(5) sage: v[3] = a sage: parent(v[3]) Integer Ring sage: parent(a) Rational Field sage: v[3] = 2/3 Traceback (most recent call last): ... TypeError: no coercion of this rational to integer
Sequences can be used absolutely anywhere lists or tuples can be used:
sage: isinstance(v, list) True
Sequence can be immutable, so entries can't be changed:
sage: v = Sequence([1,2,3], immutable=True) sage: v.is_immutable() True sage: v[0] = 5 Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead.
Sequences are hashable (unlike Python lists), though the hashing is potentially slow, since it first involves conversion of the sequence to a tuple, and returning the hash of that. The hash is cached, and is only recomputed if the sequence is changed (which has a small performance penalty for assignment).
sage: v = Sequence(range(10), ZZ); v[3] = 5 sage: hash(v) 2083920238 # 32-bit -8049699692026128018 # 64-bit sage: v[0] = 10 sage: hash(v) -377547984 # 32-bit -2271601447248391376 # 64-bit
If you really know what you are doing, you can circumvent the type checking (for an efficiency gain):
sage: list.__setitem__(v, int(1), 2/3) # bad circumvention sage: v [10, 2/3, 2, 5, 4, 5, 6, 7, 8, 9] sage: list.__setitem__(v, int(1), int(2)) # not so bad circumvention
You can make a sequence with a new universe from an old sequence.
sage: w = Sequence(v, QQ) sage: w [10, 2, 2, 5, 4, 5, 6, 7, 8, 9] sage: w.universe() Rational Field sage: w[1] = 2/3 sage: w [10, 2/3, 2, 5, 4, 5, 6, 7, 8, 9]
Sequences themselves live in a category, the category of all sequences in the given universe.
sage: w.category() Category of sequences in Rational Field
This is also the parent of any sequence:
sage: w.parent() Category of sequences in Rational Field
The default universe for any sequence, if no compatible parent structure can be found, is the universe of all SAGE objects.
This example illustrates how every element of a list is taken into account when constructing a sequence.
sage: v = Sequence([1,7,6,GF(5)(3)]); v [1, 2, 1, 3] sage: v.universe() Finite Field of size 5 sage: v.parent() Category of sequences in Finite Field of size 5 sage: v.parent()([7,8,9]) [2, 3, 4]
self, x, [universe=None], [check=True], [immutable=False], [cr=False], [cr_str=None]) |
Functions: append,
category,
extend,
insert,
is_immutable,
is_mutable,
parent,
pop,
remove,
reverse,
set_immutable,
sort,
universe
self, x) |
sage: v = Sequence([1,2,3,4], immutable=True) sage: v.append(34) Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead. sage: v = Sequence([1/3,2,3,4]) sage: v.append(4) sage: type(v[4]) <type 'sage.rings.rational.Rational'>
self, iterable) |
Extend list by appending elements from the iterable.
sage: B = Sequence([1,2,3]) sage: B.extend(range(4)) sage: B [1, 2, 3, 0, 1, 2, 3]
self, index, object) |
Insert object before index.
sage: B = Sequence([1,2,3]) sage: B.insert(10, 5) sage: B [1, 2, 3, 5]
self) |
Return True if this object is immutable (can not be changed) and False if it is not.
To make this object immutable use self.set_immutable().
sage: v = Sequence([1,2,3,4/5]) sage: v[0] = 5 sage: v [5, 2, 3, 4/5] sage: v.is_immutable() False sage: v.set_immutable() sage: v.is_immutable() True
self, [index=-1]) |
remove and return item at index (default last)
sage: B = Sequence([1,2,3]) sage: B.pop(1) 2 sage: B [1, 3]
self, value) |
Remove first occurrence of value
sage: B = Sequence([1,2,3]) sage: B.remove(2) sage: B [1, 3]
self) |
Reverse the elements of self, in place.
sage: B = Sequence([1,2,3]) sage: B.reverse(); B [3, 2, 1]
self) |
Make this object immutable, so it can never again be changed.
sage: v = Sequence([1,2,3,4/5]) sage: v[0] = 5 sage: v [5, 2, 3, 4/5] sage: v.set_immutable() sage: v[3] = 7 Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead.
self, [cmp=None], [key=None], [reverse=False]) |
Sort this list *IN PLACE*.
cmp(x, y) -> -1, 0, 1
sage: B = Sequence([3,2,1/5]) sage: B.sort() sage: B [1/5, 2, 3] sage: B.sort(reverse=True); B [3, 2, 1/5] sage: B.sort(cmp = lambda x,y: cmp(y,x)); B [3, 2, 1/5] sage: B.sort(cmp = lambda x,y: cmp(y,x), reverse=True); B [1/5, 2, 3]
Special Functions: __copy__,
__getslice__,
__init__,
__setitem__,
__setslice__,
__str__,
_repr_,
_require_mutable
self) |
Return a copy of this sequence
sage: s = seq(range(10)) sage: t = copy(s) sage: t == s True sage: t.is_immutable == s.is_immutable True sage: t.is_mutable == s.is_mutable True sage: t.parent() == s.parent() True
self, i, j) |
sage: v = Sequence([1,2,3,4], immutable=True) sage: w = v[2:] sage: w [3, 4] sage: type(w) <class 'sage.structure.sequence.Sequence'> sage: w[0] = 5; w [5, 4] sage: v [1, 2, 3, 4]
self, i, j, seq) |
sage: v = Sequence([1,2,3,4], immutable=True) sage: v[1:3] = [5,7] Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead. sage: v = Sequence([1,2,3,4]) sage: v[1:3] = [5, 3/1] sage: v [1, 5, 3, 4] sage: type(v[2]) <type 'sage.rings.integer.Integer'>
self) |
sage: s = Sequence([1,2,3], cr=False) sage: str(s) '[1, 2, 3]' sage: repr(s) '[1, 2, 3]' sage: print s [1, 2, 3] sage: s = Sequence([1,2,3], cr=True) sage: str(s) '[ 1, 2, 3 ]'
Class: Sequence
A universe is either an object that supports coercion (e.g., a parent), or a category.
Input:
sage: v = Sequence(range(10)) sage: v.universe() <type 'int'> sage: v [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
You can also use seq for "Sequence", which is identical to using Sequence:
sage: v = seq([1,2,1/1]); v [1, 2, 1] sage: v.universe() Rational Field sage: v.parent() Category of sequences in Rational Field sage: v.parent()([3,4/3]) [3, 4/3]
Note that assignment coerces if possible,
sage: v = Sequence(range(10), ZZ) sage: a = QQ(5) sage: v[3] = a sage: parent(v[3]) Integer Ring sage: parent(a) Rational Field sage: v[3] = 2/3 Traceback (most recent call last): ... TypeError: no coercion of this rational to integer
Sequences can be used absolutely anywhere lists or tuples can be used:
sage: isinstance(v, list) True
Sequence can be immutable, so entries can't be changed:
sage: v = Sequence([1,2,3], immutable=True) sage: v.is_immutable() True sage: v[0] = 5 Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead.
Sequences are hashable (unlike Python lists), though the hashing is potentially slow, since it first involves conversion of the sequence to a tuple, and returning the hash of that. The hash is cached, and is only recomputed if the sequence is changed (which has a small performance penalty for assignment).
sage: v = Sequence(range(10), ZZ); v[3] = 5 sage: hash(v) 2083920238 # 32-bit -8049699692026128018 # 64-bit sage: v[0] = 10 sage: hash(v) -377547984 # 32-bit -2271601447248391376 # 64-bit
If you really know what you are doing, you can circumvent the type checking (for an efficiency gain):
sage: list.__setitem__(v, int(1), 2/3) # bad circumvention sage: v [10, 2/3, 2, 5, 4, 5, 6, 7, 8, 9] sage: list.__setitem__(v, int(1), int(2)) # not so bad circumvention
You can make a sequence with a new universe from an old sequence.
sage: w = Sequence(v, QQ) sage: w [10, 2, 2, 5, 4, 5, 6, 7, 8, 9] sage: w.universe() Rational Field sage: w[1] = 2/3 sage: w [10, 2/3, 2, 5, 4, 5, 6, 7, 8, 9]
Sequences themselves live in a category, the category of all sequences in the given universe.
sage: w.category() Category of sequences in Rational Field
This is also the parent of any sequence:
sage: w.parent() Category of sequences in Rational Field
The default universe for any sequence, if no compatible parent structure can be found, is the universe of all SAGE objects.
This example illustrates how every element of a list is taken into account when constructing a sequence.
sage: v = Sequence([1,7,6,GF(5)(3)]); v [1, 2, 1, 3] sage: v.universe() Finite Field of size 5 sage: v.parent() Category of sequences in Finite Field of size 5 sage: v.parent()([7,8,9]) [2, 3, 4]
self, x, [universe=None], [check=True], [immutable=False], [cr=False], [cr_str=None]) |
Functions: append,
category,
extend,
insert,
is_immutable,
is_mutable,
parent,
pop,
remove,
reverse,
set_immutable,
sort,
universe
self, x) |
sage: v = Sequence([1,2,3,4], immutable=True) sage: v.append(34) Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead. sage: v = Sequence([1/3,2,3,4]) sage: v.append(4) sage: type(v[4]) <type 'sage.rings.rational.Rational'>
self, iterable) |
Extend list by appending elements from the iterable.
sage: B = Sequence([1,2,3]) sage: B.extend(range(4)) sage: B [1, 2, 3, 0, 1, 2, 3]
self, index, object) |
Insert object before index.
sage: B = Sequence([1,2,3]) sage: B.insert(10, 5) sage: B [1, 2, 3, 5]
self) |
Return True if this object is immutable (can not be changed) and False if it is not.
To make this object immutable use self.set_immutable().
sage: v = Sequence([1,2,3,4/5]) sage: v[0] = 5 sage: v [5, 2, 3, 4/5] sage: v.is_immutable() False sage: v.set_immutable() sage: v.is_immutable() True
self, [index=-1]) |
remove and return item at index (default last)
sage: B = Sequence([1,2,3]) sage: B.pop(1) 2 sage: B [1, 3]
self, value) |
Remove first occurrence of value
sage: B = Sequence([1,2,3]) sage: B.remove(2) sage: B [1, 3]
self) |
Reverse the elements of self, in place.
sage: B = Sequence([1,2,3]) sage: B.reverse(); B [3, 2, 1]
self) |
Make this object immutable, so it can never again be changed.
sage: v = Sequence([1,2,3,4/5]) sage: v[0] = 5 sage: v [5, 2, 3, 4/5] sage: v.set_immutable() sage: v[3] = 7 Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead.
self, [cmp=None], [key=None], [reverse=False]) |
Sort this list *IN PLACE*.
cmp(x, y) -> -1, 0, 1
sage: B = Sequence([3,2,1/5]) sage: B.sort() sage: B [1/5, 2, 3] sage: B.sort(reverse=True); B [3, 2, 1/5] sage: B.sort(cmp = lambda x,y: cmp(y,x)); B [3, 2, 1/5] sage: B.sort(cmp = lambda x,y: cmp(y,x), reverse=True); B [1/5, 2, 3]
Special Functions: __copy__,
__getslice__,
__init__,
__setitem__,
__setslice__,
__str__,
_repr_,
_require_mutable
self) |
Return a copy of this sequence
sage: s = seq(range(10)) sage: t = copy(s) sage: t == s True sage: t.is_immutable == s.is_immutable True sage: t.is_mutable == s.is_mutable True sage: t.parent() == s.parent() True
self, i, j) |
sage: v = Sequence([1,2,3,4], immutable=True) sage: w = v[2:] sage: w [3, 4] sage: type(w) <class 'sage.structure.sequence.Sequence'> sage: w[0] = 5; w [5, 4] sage: v [1, 2, 3, 4]
self, i, j, seq) |
sage: v = Sequence([1,2,3,4], immutable=True) sage: v[1:3] = [5,7] Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead. sage: v = Sequence([1,2,3,4]) sage: v[1:3] = [5, 3/1] sage: v [1, 5, 3, 4] sage: type(v[2]) <type 'sage.rings.integer.Integer'>
self) |
sage: s = Sequence([1,2,3], cr=False) sage: str(s) '[1, 2, 3]' sage: repr(s) '[1, 2, 3]' sage: print s [1, 2, 3] sage: s = Sequence([1,2,3], cr=True) sage: str(s) '[ 1, 2, 3 ]'
See About this document... for information on suggesting changes.