sets.gsl 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. .import:: CommonSet, NodeSet, NodeSet+, ImmNodeSet, MutNodeSet, iterable+, Any+, boolean,
  2. iterator, int
  3. ..from: kindnames
  4. .kind:: module_sets
  5. ..method:: mutnodeset
  6. ...optionals
  7. ....arg: elements:iterable+
  8. ...returns: MutNodeSet
  9. ....d: a new mutable nodeset with specified elements.
  10. ..method:: immnodeset
  11. ...optionals
  12. ....arg: elements:iterable+
  13. ...returns: ImmNodeSet
  14. ....d: a new immutable nodeset with specified elements.
  15. .and: CommonSet
  16. ..condition:: contains
  17. ...arg: x
  18. ...arg: y
  19. ...d: True if the set x contains the element y.
  20. ...python code: y in x
  21. ..condition:: empty
  22. ...self: x
  23. ...d: True if the set x is empty.
  24. ...python code: not x
  25. ..condition:: equalset
  26. ...arg: x
  27. ...arg: y
  28. ...d: True if x contains the same elements as y.
  29. ...python code: immnodeset(x) == immnodeset(y)
  30. ....in context: from guppy.sets import immnodeset
  31. ..condition:: istrue
  32. ...arg: x
  33. ...d: True if the argument is true in the Python sense.
  34. ...python code: bool(x)
  35. ..condition:: subset
  36. ...arg: x
  37. ...arg: y
  38. ...d: True if x represents a non-strict subset of y:
  39. ...d: all elements in x are also in y.
  40. ...python code: immnodeset(x) <= immnodeset(y)
  41. ....in context: from guppy.sets import immnodeset
  42. .and: NodeSet
  43. ..d
  44. A nodeset is a set of objects with equality based on heap address.
  45. ..self: x
  46. ..op: &
  47. ...d:
  48. Intersection: the set of objects that are in both x and y.
  49. ...arg: y: iterable+
  50. ...returns: ImmNodeSet
  51. ...postcondition: CommonSet.subset(<returned value>, x)
  52. ...postcondition: CommonSet.subset(<returned value>, y)
  53. ..op: |
  54. ...d:
  55. Union: the set of objects that are in either x or y.
  56. ...arg: y: iterable+
  57. ...returns: ImmNodeSet
  58. ...postcondition: CommonSet.subset(x, <returned value>)
  59. ...postcondition: CommonSet.subset(y, <returned value>)
  60. ..op: ^
  61. ...d:
  62. Symmetric set difference: the set of objects that are in exactly one of x and y.
  63. ...arg: y: iterable+
  64. ...returns: ImmNodeSet
  65. ..op: -
  66. ...d:
  67. Set difference: the set of objects that are in x but not in y.
  68. ...arg: y: iterable+
  69. ...returns: ImmNodeSet
  70. ..iop: &=
  71. ...d:
  72. In-place intersection.
  73. ...arg: y: iterable+
  74. ...returns: NodeSet
  75. ...postcondition: CommonSet.subset(<returned value>, x)
  76. ...postcondition: CommonSet.subset(<returned value>, y)
  77. ..iop: |=
  78. ...d:
  79. In-place union.
  80. ...arg: y: iterable+
  81. ...returns: NodeSet
  82. ...postcondition: CommonSet.subset(x, <returned value>)
  83. ...postcondition: CommonSet.subset(y, <returned value>)
  84. ..iop: ^=
  85. ...d:
  86. In-place symmetric set difference.
  87. ...arg: y: iterable+
  88. ...returns: NodeSet
  89. ..iop: -=
  90. ...d:
  91. In-place set difference.
  92. ...arg: y: iterable+
  93. ...returns: NodeSet
  94. ..rop: in
  95. ...d:
  96. Inclusion test.
  97. ...arg: y: Any+
  98. ...returns: boolean
  99. ..op: ==
  100. ...d:
  101. Equal:
  102. x and y contain the same elements.
  103. ...arg: y: NodeSet+
  104. ...returns: boolean
  105. ..op: !=
  106. ...d:
  107. Not equal:
  108. x and y do not contain the same elements.
  109. ...arg: y: NodeSet+
  110. ...returns: boolean
  111. ..op: <=
  112. ...d:
  113. Subset, non-strict:
  114. all elements in x are also in y.
  115. ...arg: y: NodeSet+
  116. ...returns: boolean
  117. ..op: <
  118. ...d:
  119. Subset, strict:
  120. all elements in x are also in y,
  121. and y contains some element not in x.
  122. ...arg: y: NodeSet+
  123. ...returns: boolean
  124. ..op: >=
  125. ...d:
  126. Superset, non-strict:
  127. all elements in y are also in x.
  128. ...arg: y: NodeSet+
  129. ...returns: boolean
  130. ..op: >
  131. ...d:
  132. Superset, strict:
  133. all elements in y are also in x,
  134. and x contains some element not in y.
  135. ...arg: y: NodeSet+
  136. ...returns: boolean
  137. ..fop: iter
  138. ...d: Iteration
  139. ...returns: iterator
  140. ....d:an iterator yielding the elements of x.
  141. ....d:(The order is implementation dependent.)
  142. ...postcondition: CommonSet.equalset(<returned value>, x)
  143. ..fop: len
  144. ...d: Length
  145. ...returns: int
  146. ....d:the number of elements in x.
  147. .and: MutNodeSet
  148. ..d: A mutable nodeset is a nodeset object that can be updated in place.
  149. ..subkind of: NodeSet
  150. ...d: All operations from the NodeSet kind are inherited.
  151. ...d: The in-place operators (&=, |= etc) update the target set in place
  152. and return the same object.
  153. ...d: It is unspecified what happens when trying to update a mutable nodeset
  154. for which an iterator object (from the iter() function) is active.
  155. ..self: S
  156. ..constructor: module_sets.mutnodeset
  157. ..attr:: add
  158. ...mapping
  159. ....d: Add e to S; no effect if e was already in S.
  160. ....arg: e:Any+
  161. ....postcondition: CommonSet.contains(S, e)
  162. ....postcondition: not CommonSet.empty(S)
  163. ..attr:: append
  164. ...mapping
  165. ....d: Add e to S, or raise ValueError if e was already in S.
  166. ....arg: e:Any+
  167. ....precondition: not CommonSet.contains(S, e)
  168. ....postcondition: CommonSet.contains(S, e)
  169. ....postcondition: not CommonSet.empty(S)
  170. ..attr:: clear
  171. ...mapping
  172. ....d: Remove all elements from S, and compact its storage.
  173. ....postcondition: CommonSet.empty(S)
  174. ..attr:: discard
  175. ...mapping
  176. ....d: Remove e from S; no effect if e was not in S.
  177. ....arg: e:Any+
  178. ....postcondition: not CommonSet.contains(S, e)
  179. ..attr:: pop
  180. ...mapping
  181. ....d: Remove and return some object from S, or raise ValueError if S was empty.
  182. ....precondition: not CommonSet.empty(S)
  183. ....postcondition: not CommonSet.contains(S, <returned value>)
  184. ..attr:: remove
  185. ...mapping
  186. ....d: Remove e from S, or raise ValueError if e was not in S.
  187. ....arg: e:Any+
  188. ....precondition: CommonSet.contains(S, e)
  189. ....postcondition: not CommonSet.contains(S, e)
  190. ..attr:: tas
  191. ...mapping
  192. ....d: Test and Set.
  193. ....d: If e is in S return True,
  194. ....d: else add e to S and return False.
  195. ....arg: e:Any+
  196. ....returns: boolean
  197. ....postcondition: CommonSet.contains(S, e)
  198. ....postcondition: not CommonSet.empty(S)
  199. ....equation:
  200. .....precondition: CommonSet.contains(S, e)
  201. .....postcondition: CommonSet.istrue(<returned value>)
  202. ..attr:: tac
  203. ...mapping
  204. ....d: Test and Clear.
  205. ....d: If e is in S, remove e from S and return True,
  206. ....d: else return False.
  207. ....arg: e:Any+
  208. ....returns: boolean
  209. ....postcondition: not CommonSet.contains(S, e)
  210. ....equation:
  211. .....precondition: CommonSet.contains(S, e)
  212. .....postcondition: CommonSet.istrue(<returned value>)
  213. .and: ImmNodeSet
  214. ..d: An immutable nodeset is a nodeset object that is guaranteed to always
  215. contain the same elements after it has been created.
  216. ..subkind of: NodeSet
  217. ...d: An immutable nodeset inherits the operations defined for NodeSet.
  218. ...d: The in-place operations (&=, |= etc) will not really update the
  219. target set in place, but will return an updated copy. It is yet formally
  220. unspecified whether this returned copy is mutable or immutable.
  221. ..self: x
  222. ..constructor: module_sets.immnodeset
  223. ..fop: hash
  224. ...d: Hashing
  225. ...returns: int
  226. ....d: a hash value based on the addresses of the elements.