Ticket #11407: trac_11407-list_clone_improve-fh.patch

File trac_11407-list_clone_improve-fh.patch, 50.5 KB (added by hivert, 14 months ago)

  • doc/en/reference/structure.rst 

    # HG changeset patch
# User Florent Hivert <Florent.Hivert@univ-rouen.fr>
# Date 1332431268 -3600
# Node ID 2a373127be0b76d2b15df8953698233920c549cb
# Parent  e4143acca6f448dfdc2e519730f6f04328044b35
#11407: Add normalization to clonable lists

diff --git a/doc/en/reference/structure.rst b/doc/en/reference/structure.rst
    a b Basic Structures 
    1313   sage/structure/unique_representation 
    1414   sage/structure/dynamic_class 
    1515   sage/structure/list_clone 
     16   sage/structure/list_clone_demo 
    1617   sage/structure/mutability 
    1718   sage/structure/sequence 
    1819   sage/structure/element_wrapper 

  • module_list.py 

    diff --git a/module_list.py b/module_list.py
    a b ext_modules = [ 
    189189 
    190190    Extension('sage.structure.list_clone', 
    191191              sources=['sage/structure/list_clone.pyx']), 
     192    Extension('sage.structure.list_clone_demo', 
     193              sources=['sage/structure/list_clone_demo.pyx']), 
    192194    Extension('sage.structure.list_clone_timings_cy', 
    193195              sources=['sage/structure/list_clone_timings_cy.pyx']), 
    194196 

  • sage/structure/all.py 

    diff --git a/sage/structure/all.py b/sage/structure/all.py
    a b from formal_sum import FormalSums, Form 
    4949from mutability  import Mutability 
    5050 
    5151from element_wrapper import ElementWrapper 
    52  
    53 from list_clone import (ClonableElement, ClonableArray, ClonableIntArray) 

  • sage/structure/list_clone.pxd 

    diff --git a/sage/structure/list_clone.pxd b/sage/structure/list_clone.pxd
    a b cdef class ClonableList(ClonableArray): 
    4444    cpdef pop(self, int index=*) 
    4545    cpdef remove(self, el) 
    4646 
     47cdef class NormalizedClonableList(ClonableList): 
     48    cpdef inline bint __exit__(self, typ, value, tracback) except -2 
     49    cpdef normalize(self) 
     50 
    4751cdef class ClonableIntArray(ClonableElement): 
    4852    cdef int _len 
    4953    cdef int* _list 

  • sage/structure/list_clone.pyx 

    diff --git a/sage/structure/list_clone.pyx b/sage/structure/list_clone.pyx
    a b  
    1 """ 
     1r""" 
    22Elements, Array and Lists With Clone Protocol 
    33 
    44This module defines several classes which are subclasses of 
    … … and its subclasses: 
    2727 
    2828- :class:`ClonableArray` for arrays (lists of fixed length) of objects; 
    2929- :class:`ClonableList` for (resizable) lists of objects; 
     30- :class:`NormalizedClonableList` for lists of objects with a normalization method; 
    3031- :class:`ClonableIntArray` for arrays of int. 
    3132 
    32 The following parents demonstrate how to use them: 
     33.. seealso:: The following parents from :mod:`sage.structure.list_clone_demo` 
     34    demonstrate how to use them: 
    3335 
    34 - ``IncreasingArrays()`` (see :class:`IncreasingArray` and the parent class 
    35   :class:`IncreasingArrays`) 
    36 - ``IncreasingLists()`` (see :class:`IncreasingList` and the parent class 
    37   :class:`IncreasingLists`) 
    38 - ``IncreasingIntArrays()`` (see :class:`IncreasingIntArray` and the parent class 
    39   :class:`IncreasingIntArrays`) 
     36    - ``IncreasingArrays()`` (see 
     37      :class:`~sage.structure.list_clone_demo.IncreasingArray` 
     38      and the parent class 
     39      :class:`~sage.structure.list_clone_demo.IncreasingArrays`) 
     40    - ``IncreasingLists()`` (see 
     41      :class:`~sage.structure.list_clone_demo.IncreasingList` 
     42      and the parent class 
     43      :class:`~sage.structure.list_clone_demo.IncreasingLists`) 
     44    - ``SortedLists()`` (see 
     45      :class:`~sage.structure.list_clone_demo.SortedList` 
     46      and the parent class 
     47      :class:`~sage.structure.list_clone_demo.SortedLists`) 
     48    - ``IncreasingIntArrays()`` (see 
     49      :class:`~sage.structure.list_clone_demo.IncreasingIntArray` 
     50      and the parent class 
     51      :class:`~sage.structure.list_clone_demo.IncreasingIntArrays`) 
    4052 
    4153EXAMPLES: 
    4254 
    43 We now demonstrate how :class:`IncreasingArray` works, creating an instance 
    44 ``el`` through its parent ``IncreasingArrays()``:: 
     55We now demonstrate how 
     56:class:`~sage.structure.list_clone_demo.IncreasingArray` works, creating an 
     57instance ``el`` through its parent ``IncreasingArrays()``:: 
    4558 
    46     sage: from sage.structure.list_clone import IncreasingArrays 
     59    sage: from sage.structure.list_clone_demo import IncreasingArrays 
    4760    sage: P = IncreasingArrays() 
    4861    sage: P([1, 4 ,8]) 
    4962    [1, 4, 8] 
    … … from sage.structure.parent cimport Paren 
    143156###                         Basic clone elements                         ### 
    144157############################################################################ 
    145158cdef class ClonableElement(Element): 
    146     """ 
     159    r""" 
    147160    Abstract class for elements with clone protocol 
    148161 
    149162    This class is a subclass of :class:`Element<sage.structure.element.Element>` 
    … … cdef class ClonableElement(Element): 
    203216    :class:`ClonableElement`. We implement a class or pairs `(x,y)` 
    204217    such that `x < y`:: 
    205218 
     219        sage: from sage.structure.list_clone import ClonableElement 
    206220        sage: class IntPair(ClonableElement): 
    207221        ...       def __init__(self, parent, x, y): 
    208222        ...           ClonableElement.__init__(self, parent=parent) 
    … … cdef class ClonableElement(Element): 
    267281        """ 
    268282        TESTS:: 
    269283 
    270             sage: from sage.structure.list_clone import IncreasingArrays 
     284            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    271285            sage: el = IncreasingArrays()([1,2,3]) # indirect doctest 
    272286            sage: el.is_immutable() 
    273287            True 
    … … cdef class ClonableElement(Element): 
    284298 
    285299        TESTS:: 
    286300 
    287             sage: from sage.structure.list_clone import IncreasingArrays 
     301            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    288302            sage: el = IncreasingArrays()([1,2,3]) 
    289303            sage: el._require_mutable() 
    290304            Traceback (most recent call last): 
    … … cdef class ClonableElement(Element): 
    303317 
    304318        EXAMPLES:: 
    305319 
    306             sage: from sage.structure.list_clone import IncreasingArrays 
     320            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    307321            sage: el = IncreasingArrays()([1,2,3]) 
    308322            sage: el.is_mutable() 
    309323            False 
    … … cdef class ClonableElement(Element): 
    324338 
    325339        EXAMPLES:: 
    326340 
    327             sage: from sage.structure.list_clone import IncreasingArrays 
     341            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    328342            sage: el = IncreasingArrays()([1,2,3]) 
    329343            sage: el.is_immutable() 
    330344            True 
    … … cdef class ClonableElement(Element): 
    342356 
    343357        EXAMPLES:: 
    344358 
    345             sage: from sage.structure.list_clone import IncreasingArrays 
     359            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    346360            sage: el = IncreasingArrays()([1,2,3]) 
    347361            sage: el1 = copy(el); el1.is_mutable() 
    348362            True 
    … … cdef class ClonableElement(Element): 
    359373        """ 
    360374        Makes ``self`` mutable, so it can be changed. 
    361375 
    362         This function is for debugging only, you are not supposed to use it. 
     376        .. warning:: for internal use only. Casual users should make a copy 
     377             using either the :meth:`__copy__` method or the :meth:`clone` 
     378             protocol. Use only if you really know what you are doing. You 
     379             should in particular make sure that you are the only owner of 
     380             your object. 
    363381 
    364382        TESTS:: 
    365383 
    366             sage: from sage.structure.list_clone import IncreasingArrays 
     384            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    367385            sage: el = IncreasingArrays()([1,2,3]) 
    368386            sage: el._set_mutable(); el.is_mutable() 
    369387            True 
     388            sage: hash(el) 
     389            Traceback (most recent call last): 
     390            ... 
     391            ValueError: cannot hash a mutable object. 
    370392        """ 
     393        self._hash = 0 
    371394        self._is_immutable = False 
    372395 
    373396    def __hash__(self): 
    … … cdef class ClonableElement(Element): 
    376399 
    377400        TESTS:: 
    378401 
    379             sage: from sage.structure.list_clone import IncreasingArrays 
     402            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    380403            sage: el = IncreasingArrays()([1,2,3]) 
    381404            sage: hash(el)    # random 
    382405            -309690657 
    … … cdef class ClonableElement(Element): 
    403426 
    404427        EXAMPLES:: 
    405428 
    406             sage: from sage.structure.list_clone import IncreasingArrays 
     429            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    407430            sage: el = IncreasingArrays()([1,2,3]) 
    408431            sage: with el.clone() as el1: 
    409432            ...       el1[2] = 5 
    … … cdef class ClonableElement(Element): 
    421444 
    422445        TESTS:: 
    423446 
    424             sage: from sage.structure.list_clone import IncreasingArrays 
     447            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    425448            sage: el = IncreasingArrays()([1,2,3]) 
    426449            sage: el.clone().__enter__() 
    427450            [1, 2, 3] 
    … … cdef class ClonableElement(Element): 
    438461 
    439462        TESTS:: 
    440463 
    441             sage: from sage.structure.list_clone import IncreasingArrays 
     464            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    442465            sage: el = IncreasingArrays()([1,2,3]) 
    443466            sage: el1 = el.clone().__enter__() 
    444467            sage: el1.__exit__(None, None, None) 
    … … cdef class ClonableArray(ClonableElement 
    471494    :class:`Element<sage.structure.element.Element>` behave as arrays 
    472495    (i.e. lists of fixed length) and implement the clone protocol. See 
    473496    :class:`ClonableElement` for details about clone protocol. 
     497 
     498    INPUT: 
     499 
     500    - ``parent`` -- a :class:`Parent<sage.structure.parent.Parent>` 
     501    - ``lst``    -- a list 
     502    - ``check``  -- a boolean specifying if the invariant must be checked 
     503      using method :meth:`check`. 
     504    - ``immutable`` -- a boolean telling wether the created element is 
     505      immutable (defaults to ``True``) 
     506 
     507    .. seealso:: :class:`~sage.structure.list_clone_demo.IncreasingArray` for 
     508                 an example of usage. 
     509 
     510    EXAMPLES:: 
     511 
     512        sage: from sage.structure.list_clone_demo import IncreasingArrays 
     513        sage: IA = IncreasingArrays() 
     514        sage: ia1 = IA([1, 4, 6]); ia1 
     515        [1, 4, 6] 
     516        sage: with ia1.clone() as ia2: 
     517        ...       ia2[1] = 5 
     518        sage: ia2 
     519        [1, 5, 6] 
     520        sage: with ia1.clone() as ia2: 
     521        ...       ia2[1] = 7 
     522        Traceback (most recent call last): 
     523        ... 
     524        AssertionError: array is not increasing 
    474525    """ 
    475     def __init__(self, Parent parent, lst, check = True): 
     526    def __init__(self, Parent parent, lst, check = True, immutable = True): 
    476527        """ 
    477528        Initialize ``self`` 
    478529 
    479         INPUT: 
    480  
    481         - ``parent`` -- a :class:`Parent<sage.structure.parent.Parent>` 
    482         - ``lst``    -- a list 
    483         - ``check``  -- a boolean specifying if the invariant must be checked 
    484           using method :meth:`check`. 
    485  
    486530        TESTS:: 
    487531 
    488             sage: from sage.structure.list_clone import IncreasingArrays 
     532            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    489533            sage: IncreasingArrays()([1,2,3]) 
    490534            [1, 2, 3] 
    491535 
    … … cdef class ClonableArray(ClonableElement 
    506550        """ 
    507551        self._parent = parent 
    508552        self._list = list(lst) 
    509         self._is_immutable = True 
     553        self._is_immutable = immutable 
    510554        if check: 
    511555            self.check() 
    512556 
    … … cdef class ClonableArray(ClonableElement 
    514558        """ 
    515559        TESTS:: 
    516560 
    517             sage: from sage.structure.list_clone import IncreasingArrays 
     561            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    518562            sage: IncreasingArrays()([1,2,3]) 
    519563            [1, 2, 3] 
    520564        """ 
    … … cdef class ClonableArray(ClonableElement 
    526570 
    527571        EXAMPLES:: 
    528572 
    529             sage: from sage.structure.list_clone import IncreasingArrays 
     573            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    530574            sage: IncreasingArrays()([1,2,3]).__nonzero__() 
    531575            True 
    532576            sage: IncreasingArrays()([]).__nonzero__() 
    … … cdef class ClonableArray(ClonableElement 
    538582        """ 
    539583        Returns the list embedded in ``self``. 
    540584 
    541         Don't use ! For internal purpose only. 
     585        .. warning:: No copy is performed. As a consequence, modifying the 
     586           returned list is not allowed. 
    542587 
    543588        TESTS:: 
    544589 
    545             sage: from sage.structure.list_clone import IncreasingArrays 
     590            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    546591            sage: el = IncreasingArrays()([1,2,3]) 
    547592            sage: el._get_list() 
    548593            [1, 2, 3] 
    … … cdef class ClonableArray(ClonableElement 
    553598        """ 
    554599        Set the list embedded in ``self``. 
    555600 
    556         Don't use ! For internal purpose only. 
     601        .. warning:: No copy is performed. Modifying the list after calling 
     602           ``_set_list`` on it is not allowed. 
    557603 
    558604        TESTS:: 
    559605 
    560             sage: from sage.structure.list_clone import IncreasingArrays 
     606            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    561607            sage: el = IncreasingArrays()([1,2,3]) 
    562608            sage: el._set_list([1,4,5]) 
    563609            sage: el 
    … … cdef class ClonableArray(ClonableElement 
    571617 
    572618        EXAMPLES:: 
    573619 
    574             sage: from sage.structure.list_clone import IncreasingArrays 
     620            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    575621            sage: len(IncreasingArrays()([1,2,3])) 
    576622            3 
    577623        """ 
    … … cdef class ClonableArray(ClonableElement 
    585631 
    586632        EXAMPLES:: 
    587633 
    588             sage: from sage.structure.list_clone import IncreasingArrays 
     634            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    589635            sage: IncreasingArrays()([1,2,3])[1] 
    590636            2 
    591637            sage: IncreasingArrays()([1,2,3])[7] 
    … … cdef class ClonableArray(ClonableElement 
    613659 
    614660        EXAMPLES:: 
    615661 
    616             sage: from sage.structure.list_clone import IncreasingArrays 
     662            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    617663            sage: el = IncreasingArrays()([1,2,4,10]) 
    618664            sage: elc = copy(el) 
    619665            sage: elc[1] = 3; elc 
    … … cdef class ClonableArray(ClonableElement 
    639685 
    640686        EXAMPLES:: 
    641687 
    642             sage: from sage.structure.list_clone import IncreasingArrays 
     688            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    643689            sage: IncreasingArrays()([1,2,3])._getitem(1) 
    644690            2 
    645691            sage: IncreasingArrays()([1,2,3])._getitem(5) 
    … … cdef class ClonableArray(ClonableElement 
    658704 
    659705        EXAMPLES:: 
    660706 
    661             sage: from sage.structure.list_clone import IncreasingArrays 
     707            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    662708            sage: el = IncreasingArrays()([1,2,4]) 
    663709            sage: elc = copy(el) 
    664710            sage: elc._setitem(1, 3); elc 
    … … cdef class ClonableArray(ClonableElement 
    681727 
    682728        EXAMPLES:: 
    683729 
    684             sage: from sage.structure.list_clone import IncreasingArrays 
     730            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    685731            sage: el = IncreasingArrays()([1,2,4]) 
    686732            sage: list(iter(el)) 
    687733            [1, 2, 4] 
    … … cdef class ClonableArray(ClonableElement 
    703749        """ 
    704750        EXAMPLES:: 
    705751 
    706             sage: from sage.structure.list_clone import IncreasingArrays 
     752            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    707753            sage: c = IncreasingArrays()([1,2,4]) 
    708754            sage: 1 in c 
    709755            True 
    … … cdef class ClonableArray(ClonableElement 
    718764 
    719765        EXAMPLES:: 
    720766 
    721             sage: from sage.structure.list_clone import IncreasingArrays 
     767            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    722768            sage: c = IncreasingArrays()([1,2,4]) 
    723769            sage: c.index(1) 
    724770            0 
    … … cdef class ClonableArray(ClonableElement 
    742788 
    743789        EXAMPLES:: 
    744790 
    745             sage: from sage.structure.list_clone import IncreasingArrays 
     791            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    746792            sage: c = IncreasingArrays()([1,2,2,4]) 
    747793            sage: c.count(1) 
    748794            1 
    … … cdef class ClonableArray(ClonableElement 
    761807 
    762808        TESTS:: 
    763809 
    764             sage: from sage.structure.list_clone import IncreasingArrays 
     810            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    765811            sage: el = IncreasingArrays()([1,2,3]) 
    766812            sage: hash(el)    # random 
    767813            -309690657 
    … … cdef class ClonableArray(ClonableElement 
    781827        """ 
    782828        TESTS:: 
    783829 
    784             sage: from sage.structure.list_clone import IncreasingArrays 
     830            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    785831            sage: el = IncreasingArrays()([1,2,4]) 
    786832            sage: elc = copy(el) 
    787833            sage: elc == el             # indirect doctest 
    … … cdef class ClonableArray(ClonableElement 
    794840        """ 
    795841        TEST:: 
    796842 
    797             sage: from sage.structure.list_clone import IncreasingArrays 
     843            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    798844            sage: el1 = IncreasingArrays()([1,2,4]) 
    799845            sage: el2 = IncreasingArrays()([1,2,3]) 
    800846            sage: el1 == el1, el2 == el2, el1 == el2    # indirect doctest 
    … … cdef class ClonableArray(ClonableElement 
    811857 
    812858        TESTS:: 
    813859 
    814             sage: from sage.structure.list_clone import IncreasingArrays 
     860            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    815861            sage: el = IncreasingArrays()([1,2,4]) 
    816862            sage: elc = copy(el) 
    817863            sage: el[:] == elc[:] 
    … … cdef class ClonableArray(ClonableElement 
    858904 
    859905        EXAMPLES:: 
    860906 
     907            sage: from sage.structure.list_clone import ClonableArray 
    861908            sage: ClonableArray(Parent(), [1,2,3]) # indirect doctest 
    862909            Traceback (most recent call last): 
    863910            ... 
    864911            AssertionError: This should never be called, please overload 
    865             sage: from sage.structure.list_clone import IncreasingArrays 
     912            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    866913            sage: el = IncreasingArrays()([1,2,4]) # indirect doctest 
    867914        """ 
    868915        assert False, "This should never be called, please overload" 
    … … cdef class ClonableArray(ClonableElement 
    873920 
    874921        TESTS:: 
    875922 
    876             sage: from sage.structure.list_clone import IncreasingArrays 
     923            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    877924            sage: el = IncreasingArrays()([1,2,3]) 
    878925            sage: el._hash_()    # random 
    879926            -309711137 
    … … cdef class ClonableArray(ClonableElement 
    888935        """ 
    889936        TESTS:: 
    890937 
    891             sage: from sage.structure.list_clone import IncreasingArrays 
     938            sage: from sage.structure.list_clone_demo import IncreasingArrays 
    892939            sage: el = IncreasingArrays()([1,2,4]) 
    893940            sage: loads(dumps(el)) 
    894941            [1, 2, 4] 
    895942            sage: t = el.__reduce__(); t 
    896             (<built-in function _make_array_clone>, (<type 'sage.structure.list_clone.IncreasingArray'>, <class 'sage.structure.list_clone.IncreasingArrays_with_category'>, [1, 2, 4], True, True, None)) 
     943            (<built-in function _make_array_clone>, (<type 'sage.structure.list_clone_demo.IncreasingArray'>, <class 'sage.structure.list_clone_demo.IncreasingArrays_with_category'>, [1, 2, 4], True, True, None)) 
    897944            sage: t[0](*t[1]) 
    898945            [1, 2, 4] 
    899946        """ 
    … … def _make_array_clone(clas, parent, list 
    914961 
    915962    TESTS:: 
    916963 
    917         sage: from sage.structure.list_clone import _make_array_clone, IncreasingArrays 
     964        sage: from sage.structure.list_clone import _make_array_clone 
     965        sage: from sage.structure.list_clone_demo import IncreasingArrays 
    918966        sage: ILs = IncreasingArrays() 
    919967        sage: el = _make_array_clone(ILs.element_class, ILs, [1,2,3], True, True, None) 
    920968        sage: el 
    … … def _make_array_clone(clas, parent, list 
    945993    return res 
    946994 
    947995 
    948  
    949 ##################################################################### 
    950 ######                      TESTS Classes                      ###### 
    951 ##################################################################### 
    952 ##### Cython version ##### 
    953 cdef class IncreasingArray(ClonableArray): 
    954     """ 
    955     A small extension class for testing :class:`ClonableArray`. 
    956  
    957     TESTS:: 
    958  
    959         sage: from sage.structure.list_clone import IncreasingArrays 
    960         sage: TestSuite(IncreasingArrays()([1,2,3])).run() 
    961         sage: TestSuite(IncreasingArrays()([])).run() 
    962     """ 
    963  
    964     cpdef check(self): 
    965         """ 
    966         Check that ``self`` is increasing. 
    967  
    968         EXAMPLES:: 
    969  
    970             sage: from sage.structure.list_clone import IncreasingArrays 
    971             sage: IncreasingArrays()([1,2,3]) # indirect doctest 
    972             [1, 2, 3] 
    973             sage: IncreasingArrays()([3,2,1]) # indirect doctest 
    974             Traceback (most recent call last): 
    975             ... 
    976             AssertionError: array is not increasing 
    977         """ 
    978         cdef int i 
    979         for i in range(len(self)-1): 
    980             assert self._getitem(i) <= self._getitem(i+1), "array is not increasing" 
    981  
    982  
    983 ##### Parents ##### 
    984 from sage.categories.sets_cat import Sets 
    985 from sage.structure.unique_representation import UniqueRepresentation 
    986 class IncreasingArrays(UniqueRepresentation, Parent): 
    987     """ 
    988     A small (incomplete) parent for testing :class:`ClonableArray` 
    989  
    990     TESTS:: 
    991  
    992         sage: from sage.structure.list_clone import IncreasingArrays 
    993         sage: IncreasingArrays().element_class 
    994         <type 'sage.structure.list_clone.IncreasingArray'> 
    995     """ 
    996  
    997     def __init__(self): 
    998         """ 
    999         TESTS:: 
    1000  
    1001             sage: from sage.structure.list_clone import IncreasingArrays 
    1002             sage: IncreasingArrays() 
    1003             <class 'sage.structure.list_clone.IncreasingArrays_with_category'> 
    1004             sage: IncreasingArrays() == IncreasingArrays() 
    1005             True 
    1006         """ 
    1007         Parent.__init__(self, category = Sets()) 
    1008  
    1009     def _element_constructor_(self, *args, **keywords): 
    1010         """ 
    1011         TESTS:: 
    1012  
    1013             sage: from sage.structure.list_clone import IncreasingArrays 
    1014             sage: IncreasingArrays()([1])     # indirect doctest 
    1015             [1] 
    1016         """ 
    1017         return self.element_class(self, *args, **keywords) 
    1018  
    1019     Element = IncreasingArray 
    1020  
    1021  
    1022996############################################################################ 
    1023997###                      Clonable (Resizable) Lists                      ### 
    1024998############################################################################ 
    … … cdef class ClonableList(ClonableArray): 
    10301004    :class:`Element<sage.structure.element.Element>` behave as lists and 
    10311005    implement the clone protocol. See :class:`ClonableElement` for details 
    10321006    about clone protocol. 
     1007 
     1008    .. seealso:: :class:`~sage.structure.list_clone_demo.IncreasingList` for 
     1009                 an example of usage. 
    10331010    """ 
    10341011    cpdef append(self, el): 
    10351012        """ 
    … … cdef class ClonableList(ClonableArray): 
    10391016 
    10401017        EXAMPLES:: 
    10411018 
    1042             sage: from sage.structure.list_clone import IncreasingLists 
     1019            sage: from sage.structure.list_clone_demo import IncreasingLists 
    10431020            sage: el = IncreasingLists()([1]) 
    10441021            sage: el.append(3) 
    10451022            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    10681045 
    10691046        EXAMPLES:: 
    10701047 
    1071             sage: from sage.structure.list_clone import IncreasingLists 
     1048            sage: from sage.structure.list_clone_demo import IncreasingLists 
    10721049            sage: el = IncreasingLists()([1, 4, 5, 8, 9]) 
    10731050            sage: el.extend((10,11)) 
    10741051            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    11061083 
    11071084        EXAMPLES:: 
    11081085 
    1109             sage: from sage.structure.list_clone import IncreasingLists 
     1086            sage: from sage.structure.list_clone_demo import IncreasingLists 
    11101087            sage: el = IncreasingLists()([1, 4, 5, 8, 9]) 
    11111088            sage: el.insert(3, 6) 
    11121089            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    11331110 
    11341111        EXAMPLES:: 
    11351112 
    1136             sage: from sage.structure.list_clone import IncreasingLists 
     1113            sage: from sage.structure.list_clone_demo import IncreasingLists 
    11371114            sage: el = IncreasingLists()([1, 4, 5, 8, 9]) 
    11381115            sage: el.pop() 
    11391116            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    11611138 
    11621139        EXAMPLES:: 
    11631140 
    1164             sage: from sage.structure.list_clone import IncreasingLists 
     1141            sage: from sage.structure.list_clone_demo import IncreasingLists 
    11651142            sage: el = IncreasingLists()([1, 4, 5, 8, 9]) 
    11661143            sage: el.remove(4) 
    11671144            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    11881165 
    11891166        EXAMPLES:: 
    11901167 
    1191             sage: from sage.structure.list_clone import IncreasingLists 
     1168            sage: from sage.structure.list_clone_demo import IncreasingLists 
    11921169            sage: el = IncreasingLists()([1,2,4,10,15,17]) 
    11931170            sage: el[1] = 3 
    11941171            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    12161193 
    12171194        EXAMPLES:: 
    12181195 
    1219             sage: from sage.structure.list_clone import IncreasingLists 
     1196            sage: from sage.structure.list_clone_demo import IncreasingLists 
    12201197            sage: el = IncreasingLists()([1, 4, 5, 8, 9]) 
    12211198            sage: del el[3] 
    12221199            Traceback (most recent call last): 
    … … cdef class ClonableList(ClonableArray): 
    12351212        del self._list[key] 
    12361213 
    12371214 
    1238 class IncreasingLists(IncreasingArrays): 
    1239     """ 
    1240     A small (incomplete) parent for testing :class:`ClonableArray` 
    1241  
    1242     TESTS:: 
    1243  
    1244         sage: from sage.structure.list_clone import IncreasingLists 
    1245         sage: IncreasingLists().element_class 
    1246         <type 'sage.structure.list_clone.IncreasingList'> 
    1247     """ 
    1248     Element = IncreasingList 
    1249  
    1250 cdef class IncreasingList(ClonableList): 
    1251     """ 
    1252     A small extension class for testing :class:`ClonableList` 
    1253  
    1254     TESTS:: 
    1255  
    1256         sage: from sage.structure.list_clone import IncreasingLists 
    1257         sage: TestSuite(IncreasingLists()([1,2,3])).run() 
    1258         sage: TestSuite(IncreasingLists()([])).run() 
    1259     """ 
    1260  
    1261     cpdef check(self): 
    1262         """ 
    1263         Check that ``self`` is increasing 
    1264  
    1265         EXAMPLES:: 
    1266  
    1267             sage: from sage.structure.list_clone import IncreasingLists 
    1268             sage: IncreasingLists()([1,2,3]) # indirect doctest 
    1269             [1, 2, 3] 
    1270             sage: IncreasingLists()([3,2,1]) # indirect doctest 
    1271             Traceback (most recent call last): 
    1272             ... 
    1273             AssertionError: array is not increasing 
    1274         """ 
    1275         cdef int i 
    1276         for i in range(len(self)-1): 
    1277             assert self._getitem(i) < self._getitem(i+1), "array is not increasing" 
    1278  
    1279  
    1280  
    1281  
    12821215############################################################################ 
    12831216###                     Clonable Arrays of int                            ## 
    12841217############################################################################ 
    … … cdef class ClonableIntArray(ClonableElem 
    12901223    :class:`Element<sage.structure.element.Element>` behave as list of int and 
    12911224    implement the clone protocol. See :class:`ClonableElement` for details 
    12921225    about clone protocol. 
     1226 
     1227 
     1228    INPUT: 
     1229 
     1230    - ``parent`` -- a :class:`Parent<sage.structure.parent.Parent>` 
     1231    - ``lst``      -- a list 
     1232    - ``check`` -- a boolean specifying if the invariant must be checked 
     1233      using method :meth:`check` 
     1234    - ``immutable`` -- a boolean telling wether the created element is 
     1235      immutable (defaults to ``True``) 
     1236 
     1237    .. seealso:: :class:`~sage.structure.list_clone_demo.IncreasingIntArray` 
     1238                 for an example of usage. 
    12931239    """ 
    12941240    def __cinit__(self): 
    12951241        self._len = -1 
    12961242        self._list = NULL 
    12971243 
    1298     def __init__(self, Parent parent, lst, check = True): 
     1244    def __init__(self, Parent parent, lst, check = True, immutable = True): 
    12991245        """ 
    13001246        Initialize ``self`` 
    13011247 
    1302         INPUT: 
    1303  
    1304         - ``parent`` -- a :class:`Parent<sage.structure.parent.Parent>` 
    1305         - ``lst``      -- a list 
    1306         - ``check`` -- a boolean specifying if the invariant must be checked 
    1307           using method :meth:`check`. 
    1308  
    13091248        TESTS:: 
    13101249 
    1311             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1250            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    13121251            sage: IncreasingIntArrays()([1,2,3]) 
    13131252            [1, 2, 3] 
    13141253            sage: IncreasingIntArrays()((1,2,3)) 
    … … cdef class ClonableIntArray(ClonableElem 
    13301269            sage: list(iter(IncreasingIntArrays()([]))) 
    13311270            [] 
    13321271 
    1333  
    13341272        You are not supposed to do the following (giving a wrong list and 
    13351273        desactivating checks):: 
    13361274 
    … … cdef class ClonableIntArray(ClonableElem 
    13451283        for i from 0 <= i < self._len: 
    13461284            self._list[i] = lst[i] 
    13471285 
    1348         self._is_immutable = True 
     1286        self._is_immutable = immutable 
    13491287        if check: 
    13501288            self.check() 
    13511289 
    … … cdef class ClonableIntArray(ClonableElem 
    13591297 
    13601298        EXAMPLES:: 
    13611299 
    1362             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1300            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    13631301            sage: el = IncreasingIntArrays()([], check=False) 
    13641302            sage: el._alloc_(3) 
    13651303            sage: el._setitem(0, 1); el._setitem(1, 5); el._setitem(2, 8) 
    … … cdef class ClonableIntArray(ClonableElem 
    13941332        """ 
    13951333        TESTS:: 
    13961334 
    1397             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1335            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    13981336            sage: IncreasingIntArrays()([1,2,3]) 
    13991337            [1, 2, 3] 
    14001338        """ 
    … … cdef class ClonableIntArray(ClonableElem 
    14041342        """ 
    14051343        EXAMPLES:: 
    14061344 
    1407             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1345            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    14081346            sage: IncreasingIntArrays()([1,2,3]).__nonzero__() 
    14091347            True 
    14101348            sage: IncreasingIntArrays()([]).__nonzero__() 
    … … cdef class ClonableIntArray(ClonableElem 
    14181356 
    14191357        EXAMPLES:: 
    14201358 
    1421             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1359            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    14221360            sage: len(IncreasingIntArrays()([1,2,3])) 
    14231361            3 
    14241362        """ 
    … … cdef class ClonableIntArray(ClonableElem 
    14301368 
    14311369        EXAMPLE:: 
    14321370 
    1433             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1371            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    14341372            sage: I = IncreasingIntArrays()(range(5)) 
    14351373            sage: I == range(5) 
    14361374            False 
    … … cdef class ClonableIntArray(ClonableElem 
    14451383 
    14461384        EXAMPLE:: 
    14471385 
    1448             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1386            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    14491387            sage: I = IncreasingIntArrays()(range(5)) 
    14501388            sage: I == range(5) 
    14511389            False 
    … … cdef class ClonableIntArray(ClonableElem 
    14701408 
    14711409        EXAMPLES:: 
    14721410 
    1473             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1411            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    14741412            sage: el = IncreasingIntArrays()([1,2,3]) 
    14751413            sage: el[1] 
    14761414            2 
    … … cdef class ClonableIntArray(ClonableElem 
    15231461 
    15241462        EXAMPLES:: 
    15251463 
    1526             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1464            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    15271465            sage: el = IncreasingIntArrays()([1,2,4]) 
    15281466            sage: elc = copy(el) 
    15291467            sage: elc[1] = 3; elc 
    … … cdef class ClonableIntArray(ClonableElem 
    15481486 
    15491487        EXAMPLES:: 
    15501488 
    1551             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1489            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    15521490            sage: IncreasingIntArrays()([1,2,3])._getitem(1) 
    15531491            2 
    15541492        """ 
    … … cdef class ClonableIntArray(ClonableElem 
    15661504 
    15671505        EXAMPLES:: 
    15681506 
    1569             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1507            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    15701508            sage: el = IncreasingIntArrays()([1,2,4]) 
    15711509            sage: elc = copy(el) 
    15721510            sage: elc._setitem(1, 3); elc 
    … … cdef class ClonableIntArray(ClonableElem 
    15861524        """ 
    15871525        EXAMPLES:: 
    15881526 
    1589             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1527            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    15901528            sage: c = IncreasingIntArrays()([1,2,4]) 
    15911529            sage: 1 in c 
    15921530            True 
    … … cdef class ClonableIntArray(ClonableElem 
    16031541        """ 
    16041542        EXAMPLES:: 
    16051543 
    1606             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1544            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    16071545            sage: c = IncreasingIntArrays()([1,2,4]) 
    16081546            sage: c.index(1) 
    16091547            0 
    … … cdef class ClonableIntArray(ClonableElem 
    16291567 
    16301568        TESTS:: 
    16311569 
    1632             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1570            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    16331571            sage: el = IncreasingIntArrays()([1,2,3]) 
    16341572            sage: hash(el)    # random 
    16351573            -309690657 
    … … cdef class ClonableIntArray(ClonableElem 
    16491587        """ 
    16501588        TESTS:: 
    16511589 
    1652             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1590            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    16531591            sage: el = IncreasingIntArrays()([1,2,4]) 
    16541592            sage: elc = copy(el) 
    16551593            sage: elc == el             # indirect doctest 
    … … cdef class ClonableIntArray(ClonableElem 
    16621600        """ 
    16631601        TEST:: 
    16641602 
    1665             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1603            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    16661604            sage: el1 = IncreasingIntArrays()([1,2,4]) 
    16671605            sage: el2 = IncreasingIntArrays()([1,2,3]) 
    16681606            sage: el1 == el1, el2 == el2, el1 == el2    # indirect doctest 
    … … cdef class ClonableIntArray(ClonableElem 
    16721610        """ 
    16731611        cdef int i, minlen, reslen 
    16741612        cdef ClonableIntArray rgt = <ClonableIntArray>right 
     1613        if left is right: 
     1614             return 0 
    16751615        if left._list is NULL: 
    16761616            if rgt._list is NULL: 
    16771617                return 0 
    … … cdef class ClonableIntArray(ClonableElem 
    17021642 
    17031643        TESTS:: 
    17041644 
    1705             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1645            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    17061646            sage: el = IncreasingIntArrays()([1,2,4]) 
    17071647            sage: elc = copy(el) 
    17081648            sage: el[:] == elc[:] 
    … … cdef class ClonableIntArray(ClonableElem 
    17511691 
    17521692        EXAMPLES:: 
    17531693 
     1694            sage: from sage.structure.list_clone import ClonableArray 
    17541695            sage: ClonableArray(Parent(), [1,2,3]) # indirect doctest 
    17551696            Traceback (most recent call last): 
    17561697            ... 
    17571698            AssertionError: This should never be called, please overload 
    1758             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1699            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    17591700            sage: el = IncreasingIntArrays()([1,2,4]) # indirect doctest 
    17601701        """ 
    17611702        assert False, "This should never be called, please overload" 
    … … cdef class ClonableIntArray(ClonableElem 
    17661707 
    17671708        TESTS:: 
    17681709 
    1769             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1710            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    17701711            sage: el = IncreasingIntArrays()([1,2,3]) 
    17711712            sage: el._hash_()    # random 
    17721713            -309711137 
    … … cdef class ClonableIntArray(ClonableElem 
    17841725        """ 
    17851726        TESTS:: 
    17861727 
    1787             sage: from sage.structure.list_clone import IncreasingIntArrays 
     1728            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    17881729            sage: el = IncreasingIntArrays()([1,2,4]) 
    17891730            sage: loads(dumps(el)) 
    17901731            [1, 2, 4] 
    17911732            sage: t = el.__reduce__(); t 
    1792             (<built-in function _make_int_array_clone>, (<type 'sage.structure.list_clone.IncreasingIntArray'>, <class 'sage.structure.list_clone.IncreasingIntArrays_with_category'>, [1, 2, 4], True, True, None)) 
     1733            (<built-in function _make_int_array_clone>, (<type 'sage.structure.list_clone_demo.IncreasingIntArray'>, <class 'sage.structure.list_clone_demo.IncreasingIntArrays_with_category'>, [1, 2, 4], True, True, None)) 
    17931734            sage: t[0](*t[1]) 
    17941735            [1, 2, 4] 
    17951736        """ 
    … … def _make_int_array_clone(clas, parent,  
    18101751 
    18111752    TESTS:: 
    18121753 
    1813         sage: from sage.structure.list_clone import _make_int_array_clone, IncreasingIntArrays 
     1754        sage: from sage.structure.list_clone import _make_int_array_clone 
     1755        sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
    18141756        sage: ILs = IncreasingIntArrays() 
    18151757        sage: el = _make_int_array_clone(ILs.element_class, ILs, [1,2,3], True, True, None) 
    18161758        sage: el 
    … … def _make_int_array_clone(clas, parent,  
    18321774    """ 
    18331775    cdef ClonableIntArray res 
    18341776    res = <ClonableIntArray> PY_NEW(clas) 
    1835     ClonableIntArray.__init__(res, parent, lst, needs_check) 
    1836     res._is_immutable = is_immutable 
     1777    ClonableIntArray.__init__(res, parent, lst, needs_check, is_immutable) 
    18371778    if dic is not None: 
    18381779        res.__dict__ = dic 
    18391780    return res 
    18401781 
    18411782 
    1842 cdef class IncreasingIntArray(ClonableIntArray): 
     1783 
     1784cdef class NormalizedClonableList(ClonableList): 
    18431785    """ 
    1844     A small extension class for testing :class:`ClonableIntArray`. 
     1786    List with clone protocol and normal form 
    18451787 
    1846     TESTS:: 
     1788    This is a subclass of :class:`ClonableList` which call a method 
     1789    :meth:`normalize` at creation and after any modification of its instance. 
    18471790 
    1848         sage: from sage.structure.list_clone import IncreasingIntArrays 
    1849         sage: TestSuite(IncreasingIntArrays()([1,2,3])).run() 
    1850         sage: TestSuite(IncreasingIntArrays()([])).run() 
     1791    .. seealso:: :class:`~sage.structure.list_clone_demo.SortedList` for an 
     1792                 example of usage. 
     1793 
     1794    EXAMPLES: 
     1795 
     1796    We construct a sorted list through its parent:: 
     1797 
     1798        sage: from sage.structure.list_clone_demo import SortedLists 
     1799        sage: SL = SortedLists() 
     1800        sage: sl1 = SL([4,2,6,1]); sl1 
     1801        [1, 2, 4, 6] 
     1802 
     1803    Normalization is also performed atfer modification:: 
     1804 
     1805        sage: with sl1.clone() as sl2: 
     1806        ...       sl2[1] = 12 
     1807        sage: sl2 
     1808        [1, 4, 6, 12] 
    18511809    """ 
    18521810 
    1853     cpdef check(self): 
     1811    def __init__(self, Parent parent, lst, check = True, immutable = True): 
     1812        r""" 
     1813        TESTS:: 
     1814 
     1815            sage: from sage.structure.list_clone_demo import SortedList, SortedLists 
     1816            sage: SortedList(SortedLists(), [2,3,1]) 
     1817            [1, 2, 3] 
    18541818        """ 
    1855         Check that ``self`` is increasing. 
     1819        ClonableList.__init__(self, parent, lst, False, False) 
     1820        self.normalize() 
     1821        self._is_immutable = immutable 
     1822        if check: 
     1823            self.check() 
     1824 
     1825    cpdef bint __exit__(self, typ, value, tracback): 
     1826        r""" 
     1827        TESTS:: 
     1828 
     1829            sage: from sage.structure.list_clone_demo import SortedList, SortedLists 
     1830            sage: l = SortedList(SortedLists(), [2,3,1], immutable=False); l 
     1831            [1, 2, 3] 
     1832            sage: l[1] = 5; l 
     1833            [1, 5, 3] 
     1834            sage: l.__exit__(None, None, None) 
     1835            False 
     1836            sage: l 
     1837            [1, 3, 5] 
     1838        """ 
     1839        self.normalize() 
     1840        ClonableList.__exit__(self, typ, value, tracback) 
     1841 
     1842    cpdef normalize(self): 
     1843        """ 
     1844        Normalize ``self`` 
     1845 
     1846        This is an abstract method. Subclasses are supposed to overload 
     1847        :meth:`normalize`. The call ``self.normalize()`` is supposed to 
     1848 
     1849        - call ``self._require_mutable()`` to check that ``self`` is in a 
     1850          proper mutable state 
     1851        - modify ``self`` to put it in a normal form 
    18561852 
    18571853        EXAMPLES:: 
    18581854 
    1859             sage: from sage.structure.list_clone import IncreasingIntArrays 
    1860             sage: IncreasingIntArrays()([1,2,3]) # indirect doctest 
    1861             [1, 2, 3] 
    1862             sage: IncreasingIntArrays()([3,2,1]) # indirect doctest 
     1855            sage: from sage.structure.list_clone_demo import SortedList, SortedLists 
     1856            sage: l = SortedList(SortedLists(), [2,3,2], False, False) 
     1857            sage: l 
     1858            [2, 2, 3] 
     1859            sage: l.check() 
    18631860            Traceback (most recent call last): 
    18641861            ... 
    1865             AssertionError: array is not increasing 
     1862            AssertionError: list is not strictly increasing 
    18661863        """ 
    1867         cdef int i 
    1868         if not self: 
    1869             return 
    1870         for i in range(len(self)-1): 
    1871             assert self._getitem(i) < self._getitem(i+1), "array is not increasing" 
     1864        assert False, "This should never be called, please overload" 
    18721865 
    1873 class IncreasingIntArrays(IncreasingArrays): 
    1874     """ 
    1875     A small (incomplete) parent for testing :class:`ClonableIntArray` 
    1876  
    1877     TESTS:: 
    1878  
    1879         sage: from sage.structure.list_clone import IncreasingIntArrays 
    1880         sage: IncreasingIntArrays().element_class 
    1881         <type 'sage.structure.list_clone.IncreasingIntArray'> 
    1882     """ 
    1883     Element = IncreasingIntArray 

  • new file sage/structure/list_clone_demo.pyx 

    diff --git a/sage/structure/list_clone_demo.pyx b/sage/structure/list_clone_demo.pyx
new file mode 100644
    - +  
     1r""" 
     2Elements, Array and Lists With Clone Protocol, demonstration classes 
     3 
     4This module demonstrate the usage of the various classes defined in 
     5:mod:`~sage.structure.list_clone` 
     6""" 
     7 
     8#***************************************************************************** 
     9#  Copyright (C) 2011 Florent Hivert <Florent.Hivert@univ-rouen.fr> 
     10# 
     11#  Distributed under the terms of the GNU General Public License (GPL) 
     12#                  http://www.gnu.org/licenses/ 
     13#***************************************************************************** 
     14 
     15from sage.categories.sets_cat import Sets 
     16from sage.structure.unique_representation import UniqueRepresentation 
     17from sage.structure.list_clone cimport ( 
     18    ClonableArray, ClonableList, NormalizedClonableList, ClonableIntArray ) 
     19from sage.structure.parent import Parent 
     20 
     21cdef class IncreasingArray(ClonableArray): 
     22    """ 
     23    A small extension class for testing 
     24    :class:`~sage.structure.list_clone.ClonableArray`. 
     25 
     26    TESTS:: 
     27 
     28        sage: from sage.structure.list_clone_demo import IncreasingArrays 
     29        sage: TestSuite(IncreasingArrays()([1,2,3])).run() 
     30        sage: TestSuite(IncreasingArrays()([])).run() 
     31    """ 
     32 
     33    cpdef check(self): 
     34        """ 
     35        Check that ``self`` is increasing. 
     36 
     37        EXAMPLES:: 
     38 
     39            sage: from sage.structure.list_clone_demo import IncreasingArrays 
     40            sage: IncreasingArrays()([1,2,3]) # indirect doctest 
     41            [1, 2, 3] 
     42            sage: IncreasingArrays()([3,2,1]) # indirect doctest 
     43            Traceback (most recent call last): 
     44            ... 
     45            AssertionError: array is not increasing 
     46        """ 
     47        cdef int i 
     48        for i in range(len(self)-1): 
     49            assert self._getitem(i) <= self._getitem(i+1), "array is not increasing" 
     50 
     51 
     52class IncreasingArrays(UniqueRepresentation, Parent): 
     53    """ 
     54    A small (incomplete) parent for testing 
     55    :class:`~sage.structure.list_clone.ClonableArray` 
     56 
     57    TESTS:: 
     58 
     59        sage: from sage.structure.list_clone_demo import IncreasingArrays 
     60        sage: IncreasingArrays().element_class 
     61        <type 'sage.structure.list_clone_demo.IncreasingArray'> 
     62    """ 
     63 
     64    def __init__(self): 
     65        """ 
     66        TESTS:: 
     67 
     68            sage: from sage.structure.list_clone_demo import IncreasingArrays 
     69            sage: IncreasingArrays() 
     70            <class 'sage.structure.list_clone_demo.IncreasingArrays_with_category'> 
     71            sage: IncreasingArrays() == IncreasingArrays() 
     72            True 
     73        """ 
     74        Parent.__init__(self, category = Sets()) 
     75 
     76    def _element_constructor_(self, *args, **keywords): 
     77        """ 
     78        TESTS:: 
     79 
     80            sage: from sage.structure.list_clone_demo import IncreasingArrays 
     81            sage: IncreasingArrays()([1])     # indirect doctest 
     82            [1] 
     83        """ 
     84        return self.element_class(self, *args, **keywords) 
     85 
     86    Element = IncreasingArray 
     87 
     88 
     89 
     90class IncreasingLists(IncreasingArrays): 
     91    """ 
     92    A small (incomplete) parent for testing 
     93    :class:`~sage.structure.list_clone.ClonableList` 
     94 
     95    TESTS:: 
     96 
     97        sage: from sage.structure.list_clone_demo import IncreasingLists 
     98        sage: IncreasingLists().element_class 
     99        <type 'sage.structure.list_clone_demo.IncreasingList'> 
     100    """ 
     101    Element = IncreasingList 
     102 
     103cdef class IncreasingList(ClonableList): 
     104    """ 
     105    A small extension class for testing 
     106    :class:`~sage.structure.list_clone.ClonableList` 
     107 
     108    TESTS:: 
     109 
     110        sage: from sage.structure.list_clone_demo import IncreasingLists 
     111        sage: TestSuite(IncreasingLists()([1,2,3])).run() 
     112        sage: TestSuite(IncreasingLists()([])).run() 
     113    """ 
     114 
     115    cpdef check(self): 
     116        """ 
     117        Check that ``self`` is increasing 
     118 
     119        EXAMPLES:: 
     120 
     121            sage: from sage.structure.list_clone_demo import IncreasingLists 
     122            sage: IncreasingLists()([1,2,3]) # indirect doctest 
     123            [1, 2, 3] 
     124            sage: IncreasingLists()([3,2,1]) # indirect doctest 
     125            Traceback (most recent call last): 
     126            ... 
     127            AssertionError: array is not increasing 
     128        """ 
     129        cdef int i 
     130        for i in range(len(self)-1): 
     131            assert self._getitem(i) < self._getitem(i+1), "array is not increasing" 
     132 
     133 
     134 
     135cdef class IncreasingIntArray(ClonableIntArray): 
     136    """ 
     137    A small extension class for testing 
     138    :class:`~sage.structure.list_clone.ClonableIntArray`. 
     139 
     140    TESTS:: 
     141 
     142        sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
     143        sage: TestSuite(IncreasingIntArrays()([1,2,3])).run() 
     144        sage: TestSuite(IncreasingIntArrays()([])).run() 
     145    """ 
     146 
     147    cpdef check(self): 
     148        """ 
     149        Check that ``self`` is increasing. 
     150 
     151        EXAMPLES:: 
     152 
     153            sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
     154            sage: IncreasingIntArrays()([1,2,3]) # indirect doctest 
     155            [1, 2, 3] 
     156            sage: IncreasingIntArrays()([3,2,1]) # indirect doctest 
     157            Traceback (most recent call last): 
     158            ... 
     159            AssertionError: array is not increasing 
     160        """ 
     161        cdef int i 
     162        if not self: 
     163            return 
     164        for i in range(len(self)-1): 
     165            assert self._getitem(i) < self._getitem(i+1), "array is not increasing" 
     166 
     167class IncreasingIntArrays(IncreasingArrays): 
     168    """ 
     169    A small (incomplete) parent for testing 
     170    :class:`~sage.structure.list_clone.ClonableIntArray` 
     171 
     172    TESTS:: 
     173 
     174        sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
     175        sage: IncreasingIntArrays().element_class 
     176        <type 'sage.structure.list_clone_demo.IncreasingIntArray'> 
     177    """ 
     178    Element = IncreasingIntArray 
     179 
     180 
     181 
     182cdef class SortedList(NormalizedClonableList): 
     183    """ 
     184    A small extension class for testing 
     185    :class:`~sage.structure.list_clone.NormalizedClonableList`. 
     186 
     187    TESTS:: 
     188 
     189        sage: from sage.structure.list_clone_demo import IncreasingIntArrays 
     190        sage: TestSuite(IncreasingIntArrays()([1,2,3])).run() 
     191        sage: TestSuite(IncreasingIntArrays()([])).run() 
     192    """ 
     193    cpdef normalize(self): 
     194        """ 
     195        Normalize ``self`` 
     196 
     197        Sort the list stored in ``self``. 
     198 
     199        EXAMPLES:: 
     200 
     201            sage: from sage.structure.list_clone_demo import SortedList, SortedLists 
     202            sage: l = SortedList(SortedLists(), [3,1,2], False, False) 
     203            sage: l         # indirect doctest 
     204            [1, 2, 3] 
     205            sage: l[1] = 5; l 
     206            [1, 5, 3] 
     207            sage: l.normalize(); l 
     208            [1, 3, 5] 
     209        """ 
     210        self._require_mutable() 
     211        self._get_list().sort() 
     212 
     213    cpdef check(self): 
     214        """ 
     215        Check that ``self`` is strictly increasing 
     216 
     217        EXAMPLES:: 
     218 
     219            sage: from sage.structure.list_clone_demo import SortedList, SortedLists 
     220            sage: SortedLists()([1,2,3]) # indirect doctest 
     221            [1, 2, 3] 
     222            sage: SortedLists()([3,2,2]) # indirect doctest 
     223            Traceback (most recent call last): 
     224            ... 
     225            AssertionError: list is not strictly increasing 
     226        """ 
     227        for i in range(len(self)-1): 
     228            assert self._getitem(i) != self._getitem(i+1), "list is not strictly increasing" 
     229 
     230class SortedLists(IncreasingLists): 
     231    """ 
     232    A small (incomplete) parent for testing 
     233    :class:`~sage.structure.list_clone.NormalizedClonableList` 
     234 
     235    TESTS:: 
     236 
     237        sage: from sage.structure.list_clone_demo import SortedList, SortedLists 
     238        sage: SL = SortedLists() 
     239        sage: SL([3,1,2]) 
     240        [1, 2, 3] 
     241    """ 
     242    Element = SortedList 

  • sage/structure/list_clone_timings.py 

    diff --git a/sage/structure/list_clone_timings.py b/sage/structure/list_clone_timings.py
    a b Various timings using a Python class:: 
    8080#***************************************************************************** 
    8181 
    8282 
    83 from sage.structure.list_clone import ClonableArray, IncreasingArrays 
     83from sage.structure.list_clone import ClonableArray 
     84from sage.structure.list_clone_demo import IncreasingArrays 
    8485from sage.structure.list_clone_timings_cy import * 
    8586 
    8687class IncreasingArraysPy(IncreasingArrays): 
    … … class IncreasingArraysPy(IncreasingArray 
    116117##################################################################### 
    117118######                    Timings functions                    ###### 
    118119##################################################################### 
    119 from list_clone import * 
    120 from list_clone_timings_cy import * 
    121  
    122120def add1_internal(bla): 
    123121    """ 
    124122    TESTS::