1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Copyright 2004-2008 Jean Privat <jean@pryen.org>
4 # Copyright 2006-2008 Floréal Morandat <morandat@lirmm.fr>
6 # This file is free software, which comes along with NIT. This software is
7 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
8 # without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
9 # PARTICULAR PURPOSE. You can modify it is you want, provided this header
10 # is kept unaltered, and a notification of the changes is added.
11 # You are allowed to redistribute it and sell it, alone or is a part of
14 # Most minimal classes and methods.
15 # This module is the root of the standard module hierarchy.
18 import end # Mark this module is a top level one. (must be only one)
20 ###############################################################################
22 ###############################################################################
24 # The root of the class hierarchy.
25 # Each class implicitly specialize Object.
27 # Currently, Object is also used to collect all top-level methods.
29 # Type of this instance, automatically specialized in every class
31 # A common use case of the virtual type `SELF` is to type an attribute and
32 # store another instance of the same type as `self`. It can also be used as as
33 # return type to a method producing a copy of `self` or returning an instance
34 # expected to be the exact same type as self.
36 # This virtual type must be used with caution as it can hinder specialization.
37 # In fact, it imposes strict restrictions on all sub-classes and their usage.
38 # For example, using `SELF` as a return type of a method `foo`
39 # forces all subclasses to ensure that `foo` returns the correct and updated
41 # A dangerous usage take the form of a method typed by `SELF` which creates
42 # and returns a new instance.
43 # If not correctly specialized, this method would break when invoked on a
46 # A general rule for safe usage of `SELF` is to ensure that inputs typed
47 # `SELF` are stored in attributes typed `SELF` and returned by methods typed
48 # `SELF`, pretty much the same things as you would do with parameter types.
51 # The unique object identifier in the class.
52 # Unless specific code, you should not use this method.
53 # The identifier is used internally to provide a hash value.
54 fun object_id
: Int is intern
56 # Return true if `self` and `other` have the same dynamic type.
57 # Unless specific code, you should not use this method.
58 fun is_same_type
(other
: Object): Bool is intern
60 # Return true if `self` and `other` are the same instance.
61 # Unless specific code, you should use `==` instead.
62 fun is_same_instance
(other
: nullable Object): Bool is intern
64 # Have `self` and `other` the same value?
66 # The exact meaning of "same value" is left to the subclasses.
67 # Implicitly, the default implementation, is `is_same_instance`
68 fun ==(other
: nullable Object): Bool do return self.is_same_instance
(other
)
70 # Have `self` and `other` different values?
72 # != is equivalent with "not ==".
73 fun !=(other
: nullable Object): Bool do return not (self == other
)
75 # Display self on stdout (debug only).
76 # This method MUST not be used by programs, it is here for debugging
77 # only and can be removed without any notice
85 # Display class name on stdout (debug only).
86 # This method MUST not be used by programs, it is here for debugging
87 # only and can be removed without any notice
88 fun output_class_name
is intern
90 # The hash code of the object.
91 # Assuming that a == b -> a.hash == b.hash
93 # Without redefinition, it is based on the `object_id` of the instance.
94 fun hash
: Int do return object_id
/ 8
97 # The main class of the program.
98 # `Sys` is a singleton class, its only instance is `sys` defined in `Object`.
99 # `sys` is used to invoke methods on the program on the system.
101 # Instructions outside classes implicitly redefine this method.
104 # The entry point for the execution of the whole program.
105 # Its job is to call `main` but some modules may want to refine it
106 # and inject specific work before or after the main part.
109 # Number of the last error
110 fun errno
: Int is extern "sys_errno"
113 # Quit the program with a specific return code
114 fun exit
(exit_value
: Int) is intern
116 # Return the global sys object, the only instance of the `Sys` class.
117 fun sys
: Sys is intern
120 ###############################################################################
122 ###############################################################################
124 # The ancestor of class where objects are in a total order.
125 # In order to work, the method '<' has to be redefined.
127 # What `self` can be compared to?
128 type OTHER: Comparable
130 # Is `self` lesser than `other`?
131 fun <(other
: OTHER): Bool is abstract
133 # not `other` < `self`
134 # Note, the implementation must ensure that: `(x<=y) == (x<y or x==y)`
135 fun <=(other
: OTHER): Bool do return not other
< self
137 # not `self` < `other`
138 # Note, the implementation must ensure that: `(x>=y) == (x>y or x==y)`
139 fun >=(other
: OTHER): Bool do return not self < other
142 fun >(other
: OTHER): Bool do return other
< self
144 # -1 if <, +1 if > and 0 otherwise
145 # Note, the implementation must ensure that: (x<=>y == 0) == (x==y)
146 fun <=>(other
: OTHER): Int
150 else if other
< self then
158 fun is_between
(c
: OTHER, d
: OTHER): Bool
160 return c
<= self and self <= d
163 # The maximum between `self` and `other` (prefers `self` if equals).
164 fun max
(other
: OTHER): OTHER
173 # The minimum between `self` and `c` (prefer `self` if equals)
174 fun min
(c
: OTHER): OTHER
184 # Discrete total orders.
188 redef type OTHER: Discrete
191 fun successor
(i
: Int): OTHER is abstract
193 # The previous element.
194 fun predecessor
(i
: Int): OTHER is abstract
196 # The distance between self and d.
198 # assert 10.distance(15) == 5
199 # assert 'Z'.distance('A') == 25
200 fun distance
(d
: OTHER): Int
207 else if self > d
then
215 while cursor
< stop
do
216 cursor
= cursor
.successor
(1)
223 # Something that can be cloned
225 # This interface introduces the `clone` method used to duplicate an instance
226 # Its specific semantic is left to the subclasses.
230 # The specific semantic of this method is left to the subclasses;
231 # Especially, if (and how) attributes are cloned (depth vs. shallow).
233 # As a rule of thumb, the principle of least astonishment should
234 # be used to guide the semantic.
236 # Note that as the returned clone depends on the semantic,
237 # the `==` method, if redefined, should ensure the equality
238 # between an object and its clone.
239 fun clone
: SELF is abstract
242 # A numeric value supporting mathematical operations
246 redef type OTHER: Numeric
248 # Addition of `self` with `i`
249 fun +(i
: OTHER): OTHER is abstract
251 # Substraction of `i` from `self`
252 fun -(i
: OTHER): OTHER is abstract
255 fun -: OTHER is abstract
257 # Multiplication of `self` with `i`
258 fun *(i
: OTHER): OTHER is abstract
260 # Division of `self` with `i`
261 fun /(i
: OTHER): OTHER is abstract
263 # The integer part of `self`.
265 # assert (0.0).to_i == 0
266 # assert (0.9).to_i == 0
267 # assert (-0.9).to_i == 0
268 # assert (9.9).to_i == 9
269 # assert (-9.9).to_i == -9
270 fun to_i
: Int is abstract
272 # The float equivalent of `self`
274 # assert 5.to_f == 5.0
275 # assert 5.to_f != 5 # Float and Int are not equals
276 fun to_f
: Float is abstract
278 # The byte equivalent of `self`
280 # assert (-1).to_b == 0xFF.to_b
281 # assert (1.9).to_b == 1.to_b
282 fun to_b
: Byte is abstract
284 # Is this the value of zero in its domain?
285 fun is_zero
: Bool do return self == zero
287 # The value of zero in the domain of `self`
288 fun zero
: OTHER is abstract
290 # The value of `val` in the domain of `self`
292 # assert 1.0.value_of(2) == 2.0
293 # assert 1.0.value_of(2.0) == 2.0
294 # assert 1.value_of(2) == 2
295 # assert 1.value_of(2.0) == 2
296 fun value_of
(val
: Numeric): OTHER is abstract
299 ###############################################################################
301 ###############################################################################
304 # `true` and `false` are the only instances.
306 # Boolean are manipulated trough three special operators:
307 # `and`, `or`, `not`.
309 # Booleans are mainly used by conditional statement and loops.
311 redef fun object_id
is intern
312 redef fun ==(b
) is intern
313 redef fun !=(b
) is intern
314 redef fun output
is intern
315 redef fun hash
do return to_i
317 # 1 if true and 0 if false
328 # Native floating point numbers.
329 # Corresponds to C float.
333 redef type OTHER: Float
335 redef fun object_id
is intern
336 redef fun ==(i
) is intern
337 redef fun !=(i
) is intern
338 redef fun output
is intern
340 redef fun <=(i
) is intern
341 redef fun <(i
) is intern
342 redef fun >=(i
) is intern
343 redef fun >(i
) is intern
345 redef fun +(i
) is intern
346 redef fun - is intern
347 redef fun -(i
) is intern
348 redef fun *(i
) is intern
349 redef fun /(i
) is intern
351 redef fun to_i
is intern
352 redef fun to_f
do return self
353 redef fun to_b
is intern
355 redef fun zero
do return 0.0
356 redef fun value_of
(val
) do return val
.to_f
362 else if other
< self then
369 redef fun is_between
(c
, d
)
371 if self < c
or d
< self then
378 # Compare float numbers with a given precision.
380 # Because of the loss of precision in floating numbers,
381 # the `==` method is often not the best way to compare them.
384 # assert 0.01.is_approx(0.02, 0.1) == true
385 # assert 0.01.is_approx(0.02, 0.001) == false
387 fun is_approx
(other
, precision
: Float): Bool
389 assert precision
>= 0.0
390 return self <= other
+ precision
and self >= other
- precision
413 # Same as a C `unsigned char`
418 redef type OTHER: Byte
420 redef fun successor
(i
) do return self + i
.to_b
421 redef fun predecessor
(i
) do return self - i
.to_b
423 redef fun object_id
is intern
424 redef fun hash
do return self.to_i
425 redef fun ==(i
) is intern
426 redef fun !=(i
) is intern
427 redef fun output
is intern
429 redef fun <=(i
) is intern
430 redef fun <(i
) is intern
431 redef fun >=(i
) is intern
432 redef fun >(i
) is intern
433 redef fun +(i
) is intern
435 # On an Byte, unary minus will return `(256 - self) % 256`
437 # assert -(1.to_b) == 0xFF.to_b
438 # assert -(0.to_b) == 0x00.to_b
439 redef fun - is intern
440 redef fun -(i
) is intern
441 redef fun *(i
) is intern
442 redef fun /(i
) is intern
444 # Modulo of `self` with `i`.
446 # Finds the remainder of division of `self` by `i`.
448 # assert 5.to_b % 2.to_b == 1.to_b
449 # assert 10.to_b % 2.to_b == 0.to_b
450 fun %(i
: Byte): Byte is intern
452 redef fun zero
do return 0.to_b
453 redef fun value_of
(val
) do return val
.to_b
455 # `i` bits shift fo the left (aka <<)
457 # assert 5.to_b.lshift(1) == 10.to_b
458 fun lshift
(i
: Int): Byte is intern
461 fun <<(i
: Int): Byte do return lshift
(i
)
463 # `i` bits shift fo the right (aka >>)
465 # assert 5.to_b.rshift(1) == 2.to_b
466 fun rshift
(i
: Int): Byte is intern
469 fun >>(i
: Int): Byte do return rshift
(i
)
471 redef fun to_i
is intern
472 redef fun to_f
is intern
473 redef fun to_b
do return self
475 redef fun distance
(i
) do return (self - i
).to_i
481 else if other
< self then
488 redef fun is_between
(c
, d
)
490 if self < c
or d
< self then
516 # Native integer numbers.
517 # Correspond to C int.
522 redef type OTHER: Int
524 redef fun successor
(i
) do return self + i
525 redef fun predecessor
(i
) do return self - i
527 redef fun object_id
is intern
528 redef fun hash
do return self
529 redef fun ==(i
) is intern
530 redef fun !=(i
) is intern
531 redef fun output
is intern
533 redef fun <=(i
) is intern
534 redef fun <(i
) is intern
535 redef fun >=(i
) is intern
536 redef fun >(i
) is intern
537 redef fun +(i
) is intern
539 redef fun - is intern
540 redef fun -(i
) is intern
541 redef fun *(i
) is intern
542 redef fun /(i
) is intern
544 # Modulo of `self` with `i`.
546 # Finds the remainder of division of `self` by `i`.
550 fun %(i
: Int): Int is intern
552 redef fun zero
do return 0
553 redef fun value_of
(val
) do return val
.to_i
555 # `i` bits shift fo the left (aka <<)
557 # assert 5.lshift(1) == 10
558 fun lshift
(i
: Int): Int is intern
561 fun <<(i
: Int): Int do return lshift
(i
)
563 # `i` bits shift fo the right (aka >>)
565 # assert 5.rshift(1) == 2
566 fun rshift
(i
: Int): Int is intern
569 fun >>(i
: Int): Int do return rshift
(i
)
571 redef fun to_i
do return self
572 redef fun to_f
is intern
573 redef fun to_b
is intern
575 redef fun distance
(i
)
589 else if other
< self then
596 redef fun is_between
(c
, d
)
598 if self < c
or d
< self then
623 # The character whose ASCII value is `self`.
625 # assert 65.ascii == 'A'
626 # assert 10.ascii == '\n'
627 fun ascii
: Char is intern
629 # Number of digits of an integer in base `b` (plus one if negative)
631 # assert 123.digit_count(10) == 3
632 # assert 123.digit_count(2) == 7 # 1111011 in binary
633 fun digit_count
(b
: Int): Int
635 if b
== 10 then return digit_count_base_10
636 var d
: Int # number of digits
637 var n
: Int # current number
642 else if self == 0 then
651 n
= n
/ b
# euclidian division /
656 # Optimized version for base 10
657 fun digit_count_base_10
: Int
669 if val
< 10 then return result
670 if val
< 100 then return result
+1
671 if val
< 1000 then return result
+2
672 if val
< 10000 then return result
+3
678 # Return the corresponding digit character
679 # If 0 <= `self` <= 9, return the corresponding character.
680 # assert 5.to_c == '5'
681 # If 10 <= `self` <= 36, return the corresponding letter [a..z].
682 # assert 15.to_c == 'f'
685 assert self >= 0 and self <= 36 # TODO plan for this
687 return (self + '0'.ascii
).ascii
689 return (self + ('a'.ascii
- 10)).ascii
693 # The absolute value of self
695 # assert (-10).abs == 10
696 # assert 10.abs == 10
710 # Characters are denoted with simple quote.
711 # eg. `'a'` or `'\n'`.
714 redef type OTHER: Char
716 redef fun object_id
is intern
717 redef fun hash
do return ascii
718 redef fun ==(o
) is intern
719 redef fun !=(o
) is intern
720 redef fun output
is intern
722 redef fun <=(i
) is intern
723 redef fun <(i
) is intern
724 redef fun >=(i
) is intern
725 redef fun >(i
) is intern
727 redef fun successor
(i
) is intern
728 redef fun predecessor
(i
) is intern
730 redef fun distance
(c
)
732 var d
= self.ascii
- c
.ascii
740 # If `self` is a digit then return this digit else return -1.
742 # assert '5'.to_i == 5
748 else if is_digit
then
749 return self.ascii
- '0'.ascii
751 return self.to_lower
.ascii
- 'a'.ascii
+ 10
755 # the ascii value of self
757 # assert 'a'.ascii == 97
758 # assert '\n'.ascii == 10
759 fun ascii
: Int is intern
761 # Return the lower case version of self.
762 # If self is not a letter, then return self
764 # assert 'A'.to_lower == 'a'
765 # assert 'a'.to_lower == 'a'
766 # assert '$'.to_lower == '$'
770 return (ascii
+ ('a'.distance
('A'))).ascii
776 # Return the upper case version of self.
777 # If self is not a letter, then return self
779 # assert 'a'.to_upper == 'A'
780 # assert 'A'.to_upper == 'A'
781 # assert '$'.to_upper == '$'
785 return (ascii
- ('a'.distance
('A'))).ascii
791 # Is self a digit? (from '0' to '9')
793 # assert '0'.is_digit == true
794 # assert '9'.is_digit == true
795 # assert 'a'.is_digit == false
798 return self >= '0' and self <= '9'
801 # Is self a lower case letter? (from 'a' to 'z')
803 # assert 'a'.is_lower == true
804 # assert 'z'.is_lower == true
805 # assert 'A'.is_lower == false
806 # assert '$'.is_lower == false
809 return self >= 'a' and self <= 'z'
812 # Is self a upper case letter? (from 'A' to 'Z')
814 # assert 'A'.is_upper == true
815 # assert 'A'.is_upper == true
816 # assert 'z'.is_upper == false
817 # assert '$'.is_upper == false
820 return self >= 'A' and self <= 'Z'
823 # Is self a letter? (from 'A' to 'Z' and 'a' to 'z')
825 # assert 'A'.is_letter == true
826 # assert 'A'.is_letter == true
827 # assert 'z'.is_letter == true
828 # assert '$'.is_letter == false
831 return is_lower
or is_upper
834 # Is self a whitespace character?
836 # These correspond to the "Other" and "Separator" groups of the Unicode.
838 # In the ASCII encoding, this is those <= to space (0x20) plus delete (0x7F).
840 # assert 'A'.is_whitespace == false
841 # assert ','.is_whitespace == false
842 # assert ' '.is_whitespace == true
843 # assert '\t'.is_whitespace == true
844 fun is_whitespace
: Bool
847 return i
<= 0x20 or i
== 0x7F
851 # Pointer classes are used to manipulate extern C structures.
853 # Is the address behind this Object at NULL?
854 fun address_is_null
: Bool is extern "address_is_null"
856 # Free the memory pointed by this pointer
857 fun free
is extern "free"