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)
25 ###############################################################################
27 ###############################################################################
29 # The root of the class hierarchy.
30 # Each class implicitly specialize Object.
32 # Currently, Object is also used to collect all top-level methods.
34 # Type of this instance, automatically specialized in every class
36 # A common use case of the virtual type `SELF` is to type an attribute and
37 # store another instance of the same type as `self`. It can also be used as as
38 # return type to a method producing a copy of `self` or returning an instance
39 # expected to be the exact same type as self.
41 # This virtual type must be used with caution as it can hinder specialization.
42 # In fact, it imposes strict restrictions on all sub-classes and their usage.
43 # For example, using `SELF` as a return type of a method `foo`
44 # forces all subclasses to ensure that `foo` returns the correct and updated
46 # A dangerous usage take the form of a method typed by `SELF` which creates
47 # and returns a new instance.
48 # If not correctly specialized, this method would break when invoked on a
51 # A general rule for safe usage of `SELF` is to ensure that inputs typed
52 # `SELF` are stored in attributes typed `SELF` and returned by methods typed
53 # `SELF`, pretty much the same things as you would do with parameter types.
56 # The unique object identifier in the class.
57 # Unless specific code, you should not use this method.
58 # The identifier is used internally to provide a hash value.
59 fun object_id
: Int is intern
61 # Return true if `self` and `other` have the same dynamic type.
62 # Unless specific code, you should not use this method.
63 fun is_same_type
(other
: Object): Bool is intern
65 # Return true if `self` and `other` are the same instance.
66 # Unless specific code, you should use `==` instead.
67 fun is_same_instance
(other
: nullable Object): Bool is intern
69 # Have `self` and `other` the same value?
71 # The exact meaning of "same value" is left to the subclasses.
72 # Implicitly, the default implementation, is `is_same_instance`
73 fun ==(other
: nullable Object): Bool do return self.is_same_instance
(other
)
75 # Have `self` and `other` different values?
77 # != is equivalent with "not ==".
78 fun !=(other
: nullable Object): Bool do return not (self == other
)
80 # Display self on stdout (debug only).
81 # This method MUST not be used by programs, it is here for debugging
82 # only and can be removed without any notice
90 # Display class name on stdout (debug only).
91 # This method MUST not be used by programs, it is here for debugging
92 # only and can be removed without any notice
93 fun output_class_name
is intern
95 # The hash code of the object.
96 # Assuming that a == b -> a.hash == b.hash
98 # Without redefinition, it is based on the `object_id` of the instance.
99 fun hash
: Int do return object_id
/ 8
102 # The main class of the program.
103 # `Sys` is a singleton class, its only instance is `sys` defined in `Object`.
104 # `sys` is used to invoke methods on the program on the system.
106 # Instructions outside classes implicitly redefine this method.
109 # The entry point for the execution of the whole program.
110 # Its job is to call `main` but some modules may want to refine it
111 # and inject specific work before or after the main part.
114 # Number of the last error
115 fun errno
: Int `{ return errno; `}
118 # Quit the program with a specific return code
119 fun exit(exit_value: Int) is intern
121 # Return the global sys object, the only instance of the `Sys` class.
122 fun sys: Sys is intern
125 ###############################################################################
127 ###############################################################################
129 # The ancestor of class where objects are in a total order.
130 # In order to work, the method '<' has to be redefined.
132 # What `self` can be compared to?
133 type OTHER: Comparable
135 # Is `self` lesser than `other
`?
136 fun <(other: OTHER): Bool is abstract
138 # not `other
` < `self`
139 # Note, the implementation must ensure that: `(x
<=y
) == (x
<y
or x
==y
)`
140 fun <=(other: OTHER): Bool do return not other < self
142 # not `self` < `other
`
143 # Note, the implementation must ensure that: `(x
>=y
) == (x
>y
or x
==y
)`
144 fun >=(other: OTHER): Bool do return not self < other
147 fun >(other: OTHER): Bool do return other < self
149 # -1 if <, +1 if > and 0 otherwise
150 # Note, the implementation must ensure that: (x<=>y == 0) == (x==y)
151 fun <=>(other: OTHER): Int
155 else if other < self then
163 fun is_between(c: OTHER, d: OTHER): Bool
165 return c <= self and self <= d
168 # The maximum between `self` and `other
` (prefers `self` if equals).
169 fun max(other: OTHER): OTHER
178 # The minimum between `self` and `c
` (prefer `self` if equals)
179 fun min(c: OTHER): OTHER
189 # Discrete total orders.
193 redef type OTHER: Discrete
196 fun successor(i: Int): OTHER is abstract
198 # The previous element.
199 fun predecessor(i: Int): OTHER is abstract
201 # The distance between self and d.
203 # assert 10.distance(15) == 5
204 # assert 'Z'.distance('A') == 25
205 fun distance(d: OTHER): Int
212 else if self > d then
220 while cursor < stop do
221 cursor = cursor.successor(1)
228 # Something that can be cloned
230 # This interface introduces the `clone
` method used to duplicate an instance
231 # Its specific semantic is left to the subclasses.
235 # The specific semantic of this method is left to the subclasses;
236 # Especially, if (and how) attributes are cloned (depth vs. shallow).
238 # As a rule of thumb, the principle of least astonishment should
239 # be used to guide the semantic.
241 # Note that as the returned clone depends on the semantic,
242 # the `==` method, if redefined, should ensure the equality
243 # between an object and its clone.
244 fun clone: SELF is abstract
247 # A numeric value supporting mathematical operations
251 redef type OTHER: Numeric
253 # Addition of `self` with `i
`
254 fun +(i: OTHER): OTHER is abstract
256 # Substraction of `i
` from `self`
257 fun -(i: OTHER): OTHER is abstract
260 fun -: OTHER is abstract
262 # Multiplication of `self` with `i
`
263 fun *(i: OTHER): OTHER is abstract
265 # Division of `self` with `i
`
266 fun /(i: OTHER): OTHER is abstract
268 # The integer part of `self`.
270 # assert (0.0).to_i == 0
271 # assert (0.9).to_i == 0
272 # assert (-0.9).to_i == 0
273 # assert (9.9).to_i == 9
274 # assert (-9.9).to_i == -9
275 fun to_i: Int is abstract
277 # The float equivalent of `self`
279 # assert 5.to_f == 5.0
280 # assert 5.to_f != 5 # Float and Int are not equals
281 fun to_f: Float is abstract
283 # The byte equivalent of `self`
285 # assert (-1).to_b == 0xFF.to_b
286 # assert (1.9).to_b == 1.to_b
287 fun to_b: Byte is abstract
289 # Is this the value of zero in its domain?
290 fun is_zero: Bool do return self == zero
292 # The value of zero in the domain of `self`
293 fun zero: OTHER is abstract
295 # The value of `val
` in the domain of `self`
297 # assert 1.0.value_of(2) == 2.0
298 # assert 1.0.value_of(2.0) == 2.0
299 # assert 1.value_of(2) == 2
300 # assert 1.value_of(2.0) == 2
301 fun value_of(val: Numeric): OTHER is abstract
304 ###############################################################################
306 ###############################################################################
309 # `true` and `false` are the only instances.
311 # Boolean are manipulated trough three special operators:
312 # `and`, `or`, `not`.
314 # Booleans are mainly used by conditional statement and loops.
316 redef fun object_id is intern
317 redef fun ==(b) is intern
318 redef fun !=(b) is intern
319 redef fun output is intern
320 redef fun hash do return to_i
322 # 1 if true and 0 if false
333 # Native floating point numbers.
334 # Corresponds to C float.
338 redef type OTHER: Float
340 redef fun object_id is intern
341 redef fun ==(i) is intern
342 redef fun !=(i) is intern
343 redef fun output is intern
345 redef fun <=(i) is intern
346 redef fun <(i) is intern
347 redef fun >=(i) is intern
348 redef fun >(i) is intern
350 redef fun +(i) is intern
351 redef fun - is intern
352 redef fun -(i) is intern
353 redef fun *(i) is intern
354 redef fun /(i) is intern
356 redef fun to_i is intern
357 redef fun to_f do return self
358 redef fun to_b is intern
360 redef fun zero do return 0.0
361 redef fun value_of(val) do return val.to_f
367 else if other < self then
374 redef fun is_between(c, d)
376 if self < c or d < self then
383 # Compare float numbers with a given precision.
385 # Because of the loss of precision in floating numbers,
386 # the `==` method is often not the best way to compare them.
389 # assert 0.01.is_approx(0.02, 0.1) == true
390 # assert 0.01.is_approx(0.02, 0.001) == false
392 fun is_approx(other, precision: Float): Bool
394 assert precision >= 0.0
395 return self <= other + precision and self >= other - precision
418 # Same as a C `unsigned char
`
423 redef type OTHER: Byte
425 redef fun successor(i) do return self + i.to_b
426 redef fun predecessor(i) do return self - i.to_b
428 redef fun object_id is intern
429 redef fun hash do return self.to_i
430 redef fun ==(i) is intern
431 redef fun !=(i) is intern
432 redef fun output is intern
434 redef fun <=(i) is intern
435 redef fun <(i) is intern
436 redef fun >=(i) is intern
437 redef fun >(i) is intern
438 redef fun +(i) is intern
440 # On an Byte, unary minus will return `(256 - self) % 256`
442 # assert -(1.to_b) == 0xFF.to_b
443 # assert -(0.to_b) == 0x00.to_b
444 redef fun - is intern
445 redef fun -(i) is intern
446 redef fun *(i) is intern
447 redef fun /(i) is intern
449 # Modulo of `self` with `i
`.
451 # Finds the remainder of division of `self` by `i
`.
453 # assert 5.to_b % 2.to_b == 1.to_b
454 # assert 10.to_b % 2.to_b == 0.to_b
455 fun %(i: Byte): Byte is intern
457 redef fun zero do return 0.to_b
458 redef fun value_of(val) do return val.to_b
460 # `i
` bits shift fo the left (aka <<)
462 # assert 5.to_b.lshift(1) == 10.to_b
463 fun lshift(i: Int): Byte is intern
466 fun <<(i: Int): Byte do return lshift(i)
468 # `i
` bits shift fo the right (aka >>)
470 # assert 5.to_b.rshift(1) == 2.to_b
471 fun rshift(i: Int): Byte is intern
474 fun >>(i: Int): Byte do return rshift(i)
476 redef fun to_i is intern
477 redef fun to_f is intern
478 redef fun to_b do return self
480 redef fun distance(i) do return (self - i).to_i
486 else if other < self then
493 redef fun is_between(c, d)
495 if self < c or d < self then
521 # Native integer numbers.
522 # Correspond to C int.
527 redef type OTHER: Int
529 redef fun successor(i) do return self + i
530 redef fun predecessor(i) do return self - i
532 redef fun object_id is intern
533 redef fun hash do return self
534 redef fun ==(i) is intern
535 redef fun !=(i) is intern
536 redef fun output is intern
538 redef fun <=(i) is intern
539 redef fun <(i) is intern
540 redef fun >=(i) is intern
541 redef fun >(i) is intern
542 redef fun +(i) is intern
544 redef fun - is intern
545 redef fun -(i) is intern
546 redef fun *(i) is intern
547 redef fun /(i) is intern
549 # Modulo of `self` with `i
`.
551 # Finds the remainder of division of `self` by `i
`.
555 fun %(i: Int): Int is intern
557 redef fun zero do return 0
558 redef fun value_of(val) do return val.to_i
560 # `i
` bits shift fo the left (aka <<)
562 # assert 5.lshift(1) == 10
563 fun lshift(i: Int): Int is intern
566 fun <<(i: Int): Int do return lshift(i)
568 # `i
` bits shift fo the right (aka >>)
570 # assert 5.rshift(1) == 2
571 fun rshift(i: Int): Int is intern
574 fun >>(i: Int): Int do return rshift(i)
576 redef fun to_i do return self
577 redef fun to_f is intern
578 redef fun to_b is intern
580 redef fun distance(i)
594 else if other < self then
601 redef fun is_between(c, d)
603 if self < c or d < self then
628 # The character whose ASCII value is `self`.
630 # assert 65.ascii == 'A'
631 # assert 10.ascii == '\n'
632 fun ascii: Char is intern
634 # Number of digits of an integer in base `b
` (plus one if negative)
636 # assert 123.digit_count(10) == 3
637 # assert 123.digit_count(2) == 7 # 1111011 in binary
638 fun digit_count(b: Int): Int
640 if b == 10 then return digit_count_base_10
641 var d: Int # number of digits
642 var n: Int # current number
647 else if self == 0 then
656 n = n / b # euclidian division /
661 # Optimized version for base 10
662 fun digit_count_base_10: Int
674 if val < 10 then return result
675 if val < 100 then return result+1
676 if val < 1000 then return result+2
677 if val < 10000 then return result+3
683 # Return the corresponding digit character
684 # If 0 <= `self` <= 9, return the corresponding character.
685 # assert 5.to_c == '5'
686 # If 10 <= `self` <= 36, return the corresponding letter [a..z].
687 # assert 15.to_c == 'f'
690 assert self >= 0 and self <= 36 # TODO plan for this
692 return (self + '0'.ascii).ascii
694 return (self + ('a'.ascii - 10)).ascii
698 # The absolute value of self
700 # assert (-10).abs == 10
701 # assert 10.abs == 10
715 # Characters are denoted with simple quote.
716 # eg. `'a'` or `'\n'`.
719 redef type OTHER: Char
721 redef fun object_id is intern
722 redef fun hash do return ascii
723 redef fun ==(o) is intern
724 redef fun !=(o) is intern
725 redef fun output is intern
727 redef fun <=(i) is intern
728 redef fun <(i) is intern
729 redef fun >=(i) is intern
730 redef fun >(i) is intern
732 redef fun successor(i) is intern
733 redef fun predecessor(i) is intern
735 redef fun distance(c)
737 var d = self.ascii - c.ascii
745 # If `self` is a digit then return this digit else return -1.
747 # assert '5'.to_i == 5
753 else if is_digit then
754 return self.ascii - '0'.ascii
756 return self.to_lower.ascii - 'a'.ascii + 10
760 # the ascii value of self
762 # assert 'a'.ascii == 97
763 # assert '\n'.ascii == 10
764 fun ascii: Int is intern
766 # Return the lower case version of self.
767 # If self is not a letter, then return self
769 # assert 'A'.to_lower == 'a'
770 # assert 'a'.to_lower == 'a'
771 # assert '$'.to_lower == '$'
775 return (ascii + ('a'.distance('A'))).ascii
781 # Return the upper case version of self.
782 # If self is not a letter, then return self
784 # assert 'a'.to_upper == 'A'
785 # assert 'A'.to_upper == 'A'
786 # assert '$'.to_upper == '$'
790 return (ascii - ('a'.distance('A'))).ascii
796 # Is self a digit? (from '0' to '9')
798 # assert '0'.is_digit == true
799 # assert '9'.is_digit == true
800 # assert 'a'.is_digit == false
803 return self >= '0' and self <= '9'
806 # Is self a lower case letter? (from 'a' to 'z')
808 # assert 'a'.is_lower == true
809 # assert 'z'.is_lower == true
810 # assert 'A'.is_lower == false
811 # assert '$'.is_lower == false
814 return self >= 'a' and self <= 'z'
817 # Is self a upper case letter? (from 'A' to 'Z')
819 # assert 'A'.is_upper == true
820 # assert 'A'.is_upper == true
821 # assert 'z'.is_upper == false
822 # assert '$'.is_upper == false
825 return self >= 'A' and self <= 'Z'
828 # Is self a letter? (from 'A' to 'Z' and 'a' to 'z')
830 # assert 'A'.is_letter == true
831 # assert 'A'.is_letter == true
832 # assert 'z'.is_letter == true
833 # assert '$'.is_letter == false
836 return is_lower or is_upper
839 # Is self a whitespace character?
841 # These correspond to the "Other" and "Separator" groups of the Unicode.
843 # In the ASCII encoding, this is those <= to space (0x20) plus delete (0x7F).
845 # assert 'A'.is_whitespace == false
846 # assert ','.is_whitespace == false
847 # assert ' '.is_whitespace == true
848 # assert '\t'.is_whitespace == true
849 fun is_whitespace: Bool
852 return i <= 0x20 or i == 0x7F
856 # Pointer classes are used to manipulate extern C structures.
858 # Is the address behind this Object at NULL?
859 fun address_is_null: Bool `{ return self == NULL; `}
861 # Free the memory pointed by this pointer
862 fun free
`{ free(self); `}