nitlanguage / nit.git / blob
? search:


5cc05479a98cfd91bba4ab1f73e70a02efceabae
[nit.git] / lib / standard / kernel.nit
1 # This file is part of NIT ( http://www.nitlanguage.org ).
2 #
3 # Copyright 2004-2008 Jean Privat <jean@pryen.org>
4 # Copyright 2006-2008 Floréal Morandat <morandat@lirmm.fr>
5 #
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
12 # another product.
13
14 # Most minimal classes and methods.
15 # This module is the root of the standard module hierarchy.
16 module kernel
17
18 import end # Mark this module is a top level one. (must be only one)
19
20 `{
21 #include <errno.h>
22 `}
23
24 ###############################################################################
25 # System Classes #
26 ###############################################################################
27
28 # The root of the class hierarchy.
29 # Each class implicitly specialize Object.
30 #
31 # Currently, Object is also used to collect all top-level methods.
32 interface Object
33 # Type of this instance, automatically specialized in every class
34 #
35 # A common use case of the virtual type `SELF` is to type an attribute and
36 # store another instance of the same type as `self`. It can also be used as as
37 # return type to a method producing a copy of `self` or returning an instance
38 # expected to be the exact same type as self.
39 #
40 # This virtual type must be used with caution as it can hinder specialization.
41 # In fact, it imposes strict restrictions on all sub-classes and their usage.
42 # For example, using `SELF` as a return type of a method `foo`
43 # forces all subclasses to ensure that `foo` returns the correct and updated
44 # type.
45 # A dangerous usage take the form of a method typed by `SELF` which creates
46 # and returns a new instance.
47 # If not correctly specialized, this method would break when invoked on a
48 # sub-class.
49 #
50 # A general rule for safe usage of `SELF` is to ensure that inputs typed
51 # `SELF` are stored in attributes typed `SELF` and returned by methods typed
52 # `SELF`, pretty much the same things as you would do with parameter types.
53 type SELF: Object
54
55 # The unique object identifier in the class.
56 # Unless specific code, you should not use this method.
57 # The identifier is used internally to provide a hash value.
58 fun object_id: Int is intern
59
60 # Return true if `self` and `other` have the same dynamic type.
61 # Unless specific code, you should not use this method.
62 fun is_same_type(other: Object): Bool is intern
63
64 # Return true if `self` and `other` are the same instance.
65 # Unless specific code, you should use `==` instead.
66 fun is_same_instance(other: nullable Object): Bool is intern
67
68 # Have `self` and `other` the same value?
69 #
70 # The exact meaning of "same value" is let to the subclasses.
71 # Implicitly, the default implementation, is `is_same_instance`
72 fun ==(other: nullable Object): Bool do return self.is_same_instance(other)
73
74 # Have `self` and `other` different values?
75 #
76 # != is equivalent with "not ==".
77 fun !=(other: nullable Object): Bool do return not (self == other)
78
79 # Display self on stdout (debug only).
80 # This method MUST not be used by programs, it is here for debugging
81 # only and can be removed without any notice
82 fun output
83 do
84 '<'.output
85 object_id.output
86 '>'.output
87 end
88
89 # Display class name on stdout (debug only).
90 # This method MUST not be used by programs, it is here for debugging
91 # only and can be removed without any notice
92 fun output_class_name is intern
93
94 # The hash code of the object.
95 # Assuming that a == b -> a.hash == b.hash
96 #
97 # Without redefinition, it is based on the `object_id` of the instance.
98 fun hash: Int do return object_id / 8
99 end
100
101 # The main class of the program.
102 # `Sys` is a singleton class, its only instance is `sys` defined in `Object`.
103 # `sys` is used to invoke methods on the program on the system.
104 class Sys
105 # Instructions outside classes implicitly redefine this method.
106 fun main do end
107
108 # The entry point for the execution of the whole program.
109 # Its job is to call `main` but some modules may want to refine it
110 # and inject specific work before or after the main part.
111 fun run do main
112
113 # Number of the last error
114 fun errno: Int is extern `{
115 return errno;
116 `}
117 end
118
119 # Quit the program with a specific return code
120 fun exit(exit_value: Int) is intern
121
122 # Return the global sys object, the only instance of the `Sys` class.
123 fun sys: Sys is intern
124
125
126 ###############################################################################
127 # Abstract Classes #
128 ###############################################################################
129
130 # The ancestor of class where objects are in a total order.
131 # In order to work, the method '<' has to be redefined.
132 interface Comparable
133 # What `self` can be compared to?
134 type OTHER: Comparable
135
136 # Is `self` lesser than `other`?
137 fun <(other: OTHER): Bool is abstract
138
139 # not `other` < `self`
140 # Note, the implementation must ensure that: `(x<=y) == (x<y or x==y)`
141 fun <=(other: OTHER): Bool do return not other < self
142
143 # not `self` < `other`
144 # Note, the implementation must ensure that: `(x>=y) == (x>y or x==y)`
145 fun >=(other: OTHER): Bool do return not self < other
146
147 # `other` < `self`
148 fun >(other: OTHER): Bool do return other < self
149
150 # -1 if <, +1 if > and 0 otherwise
151 # Note, the implementation must ensure that: (x<=>y == 0) == (x==y)
152 fun <=>(other: OTHER): Int
153 do
154 if self < other then
155 return -1
156 else if other < self then
157 return 1
158 else
159 return 0
160 end
161 end
162
163 # c <= self <= d
164 fun is_between(c: OTHER, d: OTHER): Bool
165 do
166 return c <= self and self <= d
167 end
168
169 # The maximum between `self` and `other` (prefers `self` if equals).
170 fun max(other: OTHER): OTHER
171 do
172 if self < other then
173 return other
174 else
175 return self
176 end
177 end
178
179 # The minimum between `self` and `c` (prefer `self` if equals)
180 fun min(c: OTHER): OTHER
181 do
182 if c < self then
183 return c
184 else
185 return self
186 end
187 end
188 end
189
190 # Discrete total orders.
191 interface Discrete
192 super Comparable
193
194 redef type OTHER: Discrete
195
196 # The next element.
197 fun successor(i: Int): OTHER is abstract
198
199 # The previous element.
200 fun predecessor(i: Int): OTHER is abstract
201
202 # The distance between self and d.
203 #
204 # assert 10.distance(15) == 5
205 # assert 'Z'.distance('A') == 25
206 fun distance(d: OTHER): Int
207 do
208 var cursor: OTHER
209 var stop: OTHER
210 if self < d then
211 cursor = self
212 stop = d
213 else if self > d then
214 cursor = d
215 stop = self
216 else
217 return 0
218 end
219
220 var nb = 0
221 while cursor < stop do
222 cursor = cursor.successor(1)
223 nb += 1
224 end
225 return nb
226 end
227 end
228
229 # A numeric value supporting mathematical operations
230 interface Numeric
231 super Comparable
232
233 redef type OTHER: Numeric
234
235 # Addition of `self` with `i`
236 fun +(i: OTHER): OTHER is abstract
237
238 # Substraction of `i` from `self`
239 fun -(i: OTHER): OTHER is abstract
240
241 # Inverse of `self`
242 fun -: OTHER is abstract
243
244 # Multiplication of `self` with `i`
245 fun *(i: OTHER): OTHER is abstract
246
247 # Division of `self` with `i`
248 fun /(i: OTHER): OTHER is abstract
249
250 # The integer part of `self`.
251 #
252 # assert (0.0).to_i == 0
253 # assert (0.9).to_i == 0
254 # assert (-0.9).to_i == 0
255 # assert (9.9).to_i == 9
256 # assert (-9.9).to_i == -9
257 fun to_i: Int is abstract
258
259 # The float equivalent of `self`
260 #
261 # assert 5.to_f == 5.0
262 # assert 5.to_f != 5 # Float and Int are not equals
263 fun to_f: Float is abstract
264
265 # Is this the value of zero in its domain?
266 fun is_zero: Bool do return self == zero
267
268 # The value of zero in the domain of `self`
269 fun zero: OTHER is abstract
270
271 # The value of `val` in the domain of `self`
272 #
273 # assert 1.0.value_of(2) == 2.0
274 # assert 1.0.value_of(2.0) == 2.0
275 # assert 1.value_of(2) == 2
276 # assert 1.value_of(2.0) == 2
277 fun value_of(val: Numeric): OTHER is abstract
278 end
279
280 ###############################################################################
281 # Native classes #
282 ###############################################################################
283
284 # Native Booleans.
285 # `true` and `false` are the only instances.
286 #
287 # Boolean are manipulated trough three special operators:
288 # `and`, `or`, `not`.
289 #
290 # Booleans are mainly used by conditional statement and loops.
291 universal Bool
292 redef fun object_id is intern
293 redef fun ==(b) is intern
294 redef fun !=(b) is intern
295 redef fun output is intern
296 redef fun hash do return to_i
297
298 # 1 if true and 0 if false
299 fun to_i: Int
300 do
301 if self then
302 return 1
303 else
304 return 0
305 end
306 end
307 end
308
309 # Native floating point numbers.
310 # Corresponds to C float.
311 universal Float
312 super Numeric
313
314 redef type OTHER: Float
315
316 redef fun object_id is intern
317 redef fun ==(i) is intern
318 redef fun !=(i) is intern
319 redef fun output is intern
320
321 redef fun <=(i): Bool is intern
322 redef fun <(i): Bool is intern
323 redef fun >=(i): Bool is intern
324 redef fun >(i): Bool is intern
325
326 redef fun +(i) is intern
327 redef fun - is intern
328 redef fun -(i) is intern
329 redef fun *(i) is intern
330 redef fun /(i) is intern
331
332 redef fun to_i is intern
333 redef fun to_f do return self
334
335 redef fun zero do return 0.0
336 redef fun value_of(val) do return val.to_f
337
338 redef fun <=>(other)
339 do
340 if self < other then
341 return -1
342 else if other < self then
343 return 1
344 else
345 return 0
346 end
347 end
348
349 redef fun is_between(c, d)
350 do
351 if self < c or d < self then
352 return false
353 else
354 return true
355 end
356 end
357
358 # Compare float numbers with a given precision.
359 #
360 # Because of the loss of precision in floating numbers,
361 # the `==` method is often not the best way to compare them.
362 #
363 # ~~~
364 # assert 0.01.is_approx(0.02, 0.1) == true
365 # assert 0.01.is_approx(0.02, 0.001) == false
366 # ~~~
367 fun is_approx(other, precision: Float): Bool
368 do
369 assert precision >= 0.0
370 return self <= other + precision and self >= other - precision
371 end
372
373 redef fun max(other)
374 do
375 if self < other then
376 return other
377 else
378 return self
379 end
380 end
381
382 redef fun min(c)
383 do
384 if c < self then
385 return c
386 else
387 return self
388 end
389 end
390 end
391
392 # Native integer numbers.
393 # Correspond to C int.
394 universal Int
395 super Discrete
396 super Numeric
397
398 redef type OTHER: Int
399
400 redef fun successor(i) do return self + i
401 redef fun predecessor(i) do return self - i
402
403 redef fun object_id is intern
404 redef fun hash do return self
405 redef fun ==(i) is intern
406 redef fun !=(i) is intern
407 redef fun output is intern
408
409 redef fun <=(i) is intern
410 redef fun <(i) is intern
411 redef fun >=(i) is intern
412 redef fun >(i) is intern
413 redef fun +(i) is intern
414
415 redef fun - is intern
416 redef fun -(i) is intern
417 redef fun *(i) is intern
418 redef fun /(i) is intern
419
420 # Modulo of `self` with `i`.
421 #
422 # Finds the remainder of division of `self` by `i`.
423 #
424 # assert 5 % 2 == 1
425 # assert 10 % 2 == 0
426 fun %(i: Int): Int is intern
427
428 redef fun zero do return 0
429 redef fun value_of(val) do return val.to_i
430
431 # `i` bits shift fo the left (aka <<)
432 #
433 # assert 5.lshift(1) == 10
434 fun lshift(i: Int): Int is intern
435
436 # `i` bits shift fo the right (aka >>)
437 #
438 # assert 5.rshift(1) == 2
439 fun rshift(i: Int): Int is intern
440
441 redef fun to_i do return self
442 redef fun to_f is intern
443
444 redef fun distance(i)
445 do
446 var d = self - i
447 if d >= 0 then
448 return d
449 else
450 return -d
451 end
452 end
453
454 redef fun <=>(other)
455 do
456 if self < other then
457 return -1
458 else if other < self then
459 return 1
460 else
461 return 0
462 end
463 end
464
465 redef fun is_between(c, d)
466 do
467 if self < c or d < self then
468 return false
469 else
470 return true
471 end
472 end
473
474 redef fun max(other)
475 do
476 if self < other then
477 return other
478 else
479 return self
480 end
481 end
482
483 redef fun min(c)
484 do
485 if c < self then
486 return c
487 else
488 return self
489 end
490 end
491
492 # The character whose ASCII value is `self`.
493 #
494 # assert 65.ascii == 'A'
495 # assert 10.ascii == '\n'
496 fun ascii: Char is intern
497
498 # Number of digits of an integer in base `b` (plus one if negative)
499 #
500 # assert 123.digit_count(10) == 3
501 # assert 123.digit_count(2) == 7 # 1111011 in binary
502 fun digit_count(b: Int): Int
503 do
504 if b == 10 then return digit_count_base_10
505 var d: Int # number of digits
506 var n: Int # current number
507 # Sign
508 if self < 0 then
509 d = 1
510 n = - self
511 else if self == 0 then
512 return 1
513 else
514 d = 0
515 n = self
516 end
517 # count digits
518 while n > 0 do
519 d += 1
520 n = n / b # euclidian division /
521 end
522 return d
523 end
524
525 # Optimized version for base 10
526 fun digit_count_base_10: Int
527 do
528 var val: Int
529 var result: Int
530 if self < 0 then
531 result = 2
532 val = -self
533 else
534 result = 1
535 val = self
536 end
537 loop
538 if val < 10 then return result
539 if val < 100 then return result+1
540 if val < 1000 then return result+2
541 if val < 10000 then return result+3
542 val = val / 10000
543 result += 4
544 end
545 end
546
547 # Return the corresponding digit character
548 # If 0 <= `self` <= 9, return the corresponding character.
549 # assert 5.to_c == '5'
550 # If 10 <= `self` <= 36, return the corresponding letter [a..z].
551 # assert 15.to_c == 'f'
552 fun to_c: Char
553 do
554 assert self >= 0 and self <= 36 # TODO plan for this
555 if self < 10 then
556 return (self + '0'.ascii).ascii
557 else
558 return (self + ('a'.ascii - 10)).ascii
559 end
560 end
561
562 # The absolute value of self
563 #
564 # assert (-10).abs == 10
565 # assert 10.abs == 10
566 # assert 0.abs == 0
567 fun abs: Int
568 do
569 if self >= 0
570 then
571 return self
572 else
573 return -1 * self
574 end
575 end
576 end
577
578 # Native characters.
579 # Characters are denoted with simple quote.
580 # eg. `'a'` or `'\n'`.
581 universal Char
582 super Discrete
583 redef type OTHER: Char
584
585 redef fun object_id is intern
586 redef fun hash do return ascii
587 redef fun ==(o) is intern
588 redef fun !=(o) is intern
589 redef fun output is intern
590
591 redef fun <=(i) is intern
592 redef fun <(i) is intern
593 redef fun >=(i) is intern
594 redef fun >(i) is intern
595
596 redef fun successor(i) is intern
597 redef fun predecessor(i) is intern
598
599 redef fun distance(c)
600 do
601 var d = self.ascii - c.ascii
602 if d >= 0 then
603 return d
604 else
605 return -d
606 end
607 end
608
609 # If `self` is a digit then return this digit else return -1.
610 #
611 # assert '5'.to_i == 5
612 fun to_i: Int
613 do
614
615 if self == '-' then
616 return -1
617 else if is_digit then
618 return self.ascii - '0'.ascii
619 else
620 return self.to_lower.ascii - 'a'.ascii + 10
621 end
622 end
623
624 # the ascii value of self
625 #
626 # assert 'a'.ascii == 97
627 # assert '\n'.ascii == 10
628 fun ascii: Int is intern
629
630 # Return the lower case version of self.
631 # If self is not a letter, then return self
632 #
633 # assert 'A'.to_lower == 'a'
634 # assert 'a'.to_lower == 'a'
635 # assert '$'.to_lower == '$'
636 fun to_lower: Char
637 do
638 if is_upper then
639 return (ascii + ('a'.distance('A'))).ascii
640 else
641 return self
642 end
643 end
644
645 # Return the upper case version of self.
646 # If self is not a letter, then return self
647 #
648 # assert 'a'.to_upper == 'A'
649 # assert 'A'.to_upper == 'A'
650 # assert '$'.to_upper == '$'
651 fun to_upper: Char
652 do
653 if is_lower then
654 return (ascii - ('a'.distance('A'))).ascii
655 else
656 return self
657 end
658 end
659
660 # Is self a digit? (from '0' to '9')
661 #
662 # assert '0'.is_digit == true
663 # assert '9'.is_digit == true
664 # assert 'a'.is_digit == false
665 fun is_digit : Bool
666 do
667 return self >= '0' and self <= '9'
668 end
669
670 # Is self a lower case letter? (from 'a' to 'z')
671 #
672 # assert 'a'.is_lower == true
673 # assert 'z'.is_lower == true
674 # assert 'A'.is_lower == false
675 # assert '$'.is_lower == false
676 fun is_lower : Bool
677 do
678 return self >= 'a' and self <= 'z'
679 end
680
681 # Is self a upper case letter? (from 'A' to 'Z')
682 #
683 # assert 'A'.is_upper == true
684 # assert 'A'.is_upper == true
685 # assert 'z'.is_upper == false
686 # assert '$'.is_upper == false
687 fun is_upper : Bool
688 do
689 return self >= 'A' and self <= 'Z'
690 end
691
692 # Is self a letter? (from 'A' to 'Z' and 'a' to 'z')
693 #
694 # assert 'A'.is_letter == true
695 # assert 'A'.is_letter == true
696 # assert 'z'.is_letter == true
697 # assert '$'.is_letter == false
698 fun is_letter : Bool
699 do
700 return is_lower or is_upper
701 end
702 end
703
704 # Pointer classes are used to manipulate extern C structures.
705 extern class Pointer
706 # Is the address behind this Object at NULL?
707 fun address_is_null: Bool is extern "address_is_null"
708
709 # Free the memory pointed by this pointer
710 fun free is extern "free"
711 end
Nit language project; an oo programing language and its tool suite.