def _addElementPreProcess(self, element, checkRedundancy=True):
'''
Before adding an element, this method provides
important checks to that element.
Used by both insert() and append()
'''
# using id() here b/c we do not want to get __eq__ comparisons
if element is self: # cannot add this Stream into itself
raise StreamException(
"this Stream cannot be contained within itself")
if checkRedundancy:
idElement = id(element)
if idElement in self._offsetDict:
# now go slow for safety -- maybe something is amiss in the index.
# this should not happen, but we have slipped many times in not clearing out
# old _offsetDict entries.
for eInStream in self:
if eInStream is element:
raise StreamException(
'the object ' +
'(%s, id()=%s) is already found in this Stream (%s, id()=%s)'
% (element, id(element), self, id(self)))
# something was old... delete from _offsetDict
# environLocal.warn('stale object')
del self._offsetDict[idElement]
# if we do not purge locations here, we may have ids() for
# Stream that no longer exist stored in the locations entry
# note that dead locations are also purged from .sites during
# all get() calls.
element.purgeLocations()
def coreGuardBeforeAddElement(self, element, *, checkRedundancy=True):
'''
Before adding an element, this method performs
important checks on that element.
Used by:
- :meth:`~music21.stream.Stream.insert`
- :meth:`~music21.stream.Stream.append`
- :meth:`~music21.stream.Stream.storeAtEnd`
- `Stream.__init__()`
Returns None or raises a StreamException
>>> s = stream.Stream()
>>> s.coreGuardBeforeAddElement(s)
Traceback (most recent call last):
music21.exceptions21.StreamException: this Stream cannot be contained within itself
>>> s.append(s.iter())
Traceback (most recent call last):
music21.exceptions21.StreamException: cannot insert StreamIterator into a Stream
Iterate over it instead (User's Guide chs. 6 and 26)
>>> s.insert(4, 3.14159)
Traceback (most recent call last):
music21.exceptions21.StreamException: to put a non Music21Object in a stream,
create a music21.ElementWrapper for the item
'''
if element is self: # cannot add this Stream into itself
raise StreamException('this Stream cannot be contained within itself')
if not isinstance(element, Music21Object):
if isinstance(element, StreamIterator):
raise StreamException('cannot insert StreamIterator into a Stream\n'
"Iterate over it instead (User's Guide chs. 6 and 26)")
raise StreamException('to put a non Music21Object in a stream, '
'create a music21.ElementWrapper for the item')
if checkRedundancy:
# using id() here b/c we do not want to get __eq__ comparisons
idElement = id(element)
if idElement in self._offsetDict:
# now go slow for safety -- maybe something is amiss in the index.
# this should not happen, but we have slipped many times in not clearing out
# old _offsetDict entries.
for search_place in (self._elements, self._endElements):
for eInStream in search_place:
if eInStream is element:
raise StreamException(
f'the object ({element!r}, id()={id(element)} '
+ f'is already found in this Stream ({self!r}, id()={id(self)})'
)
# something was old... delete from _offsetDict
# environLocal.warn('stale object')
del self._offsetDict[idElement] # pragma: no cover
# if we do not purge locations here, we may have ids() for
# Streams that no longer exist stored in the locations entry for element.
# Note that dead locations are also purged from .sites during
# all get() calls.
element.purgeLocations()
def coreSetElementOffset(self,
element: Music21Object,
offset: t.Union[int, float, Fraction,
OffsetSpecial],
*,
addElement=False,
setActiveSite=True):
'''
Sets the Offset for an element, very quickly.
Caller is responsible for calling :meth:`~music21.stream.core.coreElementsChanged`
afterward.
>>> s = stream.Stream()
>>> s.id = 'Stream1'
>>> n = note.Note('B-4')
>>> s.insert(10, n)
>>> n.offset
10.0
>>> s.coreSetElementOffset(n, 20.0)
>>> n.offset
20.0
>>> n.getOffsetBySite(s)
20.0
'''
# Note: not documenting 'highestTime' is on purpose, since can only be done for
# elements already stored at end. Infinite loop.
try:
offset = opFrac(offset)
except TypeError:
if offset not in OffsetSpecial: # pragma: no cover
raise StreamException(
f'Cannot set offset to {offset!r} for {element}')
idEl = id(element)
if not addElement and idEl not in self._offsetDict:
raise StreamException(
f'Cannot set the offset for element {element}, not in Stream {self}.'
)
self._offsetDict[idEl] = (offset, element) # fast
if setActiveSite:
self.coreSelfActiveSite(element)
def coreGuardBeforeAddElement(self, element, *, checkRedundancy=True):
'''
Before adding an element, this method provides
important checks to that element.
Used by both insert() and append()
Returns None or raises a StreamException
>>> s = stream.Stream()
>>> s.coreGuardBeforeAddElement(s)
Traceback (most recent call last):
music21.exceptions21.StreamException: this Stream cannot be contained within itself
'''
# using id() here b/c we do not want to get __eq__ comparisons
if element is self: # cannot add this Stream into itself
raise StreamException(
'this Stream cannot be contained within itself')
if checkRedundancy:
idElement = id(element)
if idElement in self._offsetDict:
# now go slow for safety -- maybe something is amiss in the index.
# this should not happen, but we have slipped many times in not clearing out
# old _offsetDict entries.
for search_place in (self._elements, self._endElements):
for eInStream in search_place:
if eInStream is element:
raise StreamException(
f'the object ({element!r}, id()={id(element)} '
+
f'is already found in this Stream ({self!r}, id()={id(self)})'
)
# something was old... delete from _offsetDict
# environLocal.warn('stale object')
del self._offsetDict[idElement] # pragma: no cover
# if we do not purge locations here, we may have ids() for
# Streams that no longer exist stored in the locations entry for element.
# Note that dead locations are also purged from .sites during
# all get() calls.
element.purgeLocations()
