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 # Boolean are manipulated trough three special operators:
 287 #        `and`, `or`, `not`.
 288 # Booleans are mainly used by conditional statement and loops.
 289 universal Bool
 290         redef fun object_id is intern
 291         redef fun ==(b) is intern
 292         redef fun !=(b) is intern
 293         redef fun output is intern
 294         redef fun hash do return to_i
 295
 296         # 1 if true and 0 if false
 297         fun to_i: Int
 298         do
 299                 if self then
 300                         return 1
 301                 else
 302                         return 0
 303                 end
 304         end
 305 end
 306
 307 # Native floating point numbers.
 308 # Corresponds to C float.
 309 universal Float
 310         super Numeric
 311
 312         redef type OTHER: Float
 313
 314         redef fun object_id is intern
 315         redef fun ==(i) is intern
 316         redef fun !=(i) is intern
 317         redef fun output is intern
 318
 319         redef fun <=(i): Bool is intern
 320         redef fun <(i): Bool is intern
 321         redef fun >=(i): Bool is intern
 322         redef fun >(i): Bool is intern
 323
 324         redef fun +(i) is intern
 325         redef fun - is intern
 326         redef fun -(i) is intern
 327         redef fun *(i) is intern
 328         redef fun /(i) is intern
 329
 330         redef fun to_i is intern
 331         redef fun to_f do return self
 332
 333         redef fun zero do return 0.0
 334         redef fun value_of(val) do return val.to_f
 335
 336         redef fun <=>(other)
 337         do
 338                 if self < other then
 339                         return -1
 340                 else if other < self then
 341                         return 1
 342                 else
 343                         return 0
 344                 end
 345         end
 346
 347         redef fun is_between(c, d)
 348         do
 349                 if self < c or d < self then
 350                         return false
 351                 else
 352                         return true
 353                 end
 354         end
 355
 356         # Compare float numbers with a given precision.
 357         #
 358         # Because of the loss of precision in floating numbers,
 359         # the `==` method is often not the best way to compare them.
 360         #
 361         # ~~~
 362         # assert 0.01.is_approx(0.02, 0.1)   == true
 363         # assert 0.01.is_approx(0.02, 0.001) == false
 364         # ~~~
 365         fun is_approx(other, precision: Float): Bool
 366         do
 367                 assert precision >= 0.0
 368                 return self <= other + precision and self >= other - precision
 369         end
 370
 371         redef fun max(other)
 372         do
 373                 if self < other then
 374                         return other
 375                 else
 376                         return self
 377                 end
 378         end
 379
 380         redef fun min(c)
 381         do
 382                 if c < self then
 383                         return c
 384                 else
 385                         return self
 386                 end
 387         end
 388 end
 389
 390 # Native integer numbers.
 391 # Correspond to C int.
 392 universal Int
 393         super Discrete
 394         super Numeric
 395
 396         redef type OTHER: Int
 397
 398         redef fun successor(i) do return self + i
 399         redef fun predecessor(i) do return self - i
 400
 401         redef fun object_id is intern
 402         redef fun hash do return self
 403         redef fun ==(i) is intern
 404         redef fun !=(i) is intern
 405         redef fun output is intern
 406
 407         redef fun <=(i) is intern
 408         redef fun <(i) is intern
 409         redef fun >=(i) is intern
 410         redef fun >(i) is intern
 411         redef fun +(i) is intern
 412
 413         redef fun - is intern
 414         redef fun -(i) is intern
 415         redef fun *(i) is intern
 416         redef fun /(i) is intern
 417         fun %(i: Int): Int is intern
 418
 419         redef fun zero do return 0
 420         redef fun value_of(val) do return val.to_i
 421
 422         # `i` bits shift fo the left (aka <<)
 423         #
 424         #     assert 5.lshift(1)    == 10
 425         fun lshift(i: Int): Int is intern
 426
 427         # `i` bits shift fo the right (aka >>)
 428         #
 429         #     assert 5.rshift(1)    == 2
 430         fun rshift(i: Int): Int is intern
 431
 432         redef fun to_i do return self
 433         redef fun to_f is intern
 434
 435         redef fun distance(i)
 436         do
 437                 var d = self - i
 438                 if d >= 0 then
 439                         return d
 440                 else
 441                         return -d
 442                 end
 443         end
 444
 445         redef fun <=>(other)
 446         do
 447                 if self < other then
 448                         return -1
 449                 else if other < self then
 450                         return 1
 451                 else
 452                         return 0
 453                 end
 454         end
 455
 456         redef fun is_between(c, d)
 457         do
 458                 if self < c or d < self then
 459                         return false
 460                 else
 461                         return true
 462                 end
 463         end
 464
 465         redef fun max(other)
 466         do
 467                 if self < other then
 468                         return other
 469                 else
 470                         return self
 471                 end
 472         end
 473
 474         redef fun min(c)
 475         do
 476                 if c < self then
 477                         return c
 478                 else
 479                         return self
 480                 end
 481         end
 482
 483         # The character whose ASCII value is `self`.
 484         #
 485         #      assert 65.ascii   == 'A'
 486         #      assert 10.ascii   == '\n'
 487         fun ascii: Char is intern
 488
 489         # Number of digits of an integer in base `b` (plus one if negative)
 490         #
 491         #     assert 123.digit_count(10) == 3
 492         #     assert 123.digit_count(2) == 7 # 1111011 in binary
 493         fun digit_count(b: Int): Int
 494         do
 495                 if b == 10 then return digit_count_base_10
 496                 var d: Int # number of digits
 497                 var n: Int # current number
 498                 # Sign
 499                 if self < 0 then
 500                         d = 1
 501                         n = - self
 502                 else if self == 0 then
 503                         return 1
 504                 else
 505                         d = 0
 506                         n = self
 507                 end
 508                 # count digits
 509                 while n > 0 do
 510                         d += 1
 511                         n = n / b       # euclidian division /
 512                 end
 513                 return d
 514         end
 515
 516         # Optimized version for base 10
 517         fun digit_count_base_10: Int
 518         do
 519                 var val: Int
 520                 var result: Int
 521                 if self < 0 then
 522                         result = 2
 523                         val = -self
 524                 else
 525                         result = 1
 526                         val = self
 527                 end
 528                 loop
 529                         if val < 10 then return result
 530                         if val < 100 then return result+1
 531                         if val < 1000 then return result+2
 532                         if val < 10000 then return result+3
 533                         val = val / 10000
 534                         result += 4
 535                 end
 536         end
 537
 538         # Return the corresponding digit character
 539         # If 0 <= `self` <= 9, return the corresponding character.
 540         #     assert 5.to_c    == '5'
 541         # If 10 <= `self` <= 36, return the corresponding letter [a..z].
 542         #     assert 15.to_c   == 'f'
 543         fun to_c: Char
 544         do
 545                 assert self >= 0 and self <= 36 # TODO plan for this
 546                 if self < 10 then
 547                         return (self + '0'.ascii).ascii
 548                 else
 549                         return (self + ('a'.ascii - 10)).ascii
 550                 end
 551         end
 552
 553         # The absolute value of self
 554         #
 555         #     assert (-10).abs   == 10
 556         #     assert 10.abs    == 10
 557         #     assert 0.abs     == 0
 558         fun abs: Int
 559         do
 560             if self >= 0
 561             then
 562                 return self
 563             else
 564                 return -1 * self
 565             end
 566         end
 567 end
 568
 569 # Native characters.
 570 # Characters are denoted with simple quote.
 571 # eg. `'a'` or `'\n'`.
 572 universal Char
 573         super Discrete
 574         redef type OTHER: Char
 575
 576         redef fun object_id is intern
 577         redef fun hash do return ascii
 578         redef fun ==(o) is intern
 579         redef fun !=(o) is intern
 580         redef fun output is intern
 581
 582         redef fun <=(i) is intern
 583         redef fun <(i) is intern
 584         redef fun >=(i) is intern
 585         redef fun >(i) is intern
 586
 587         redef fun successor(i) is intern
 588         redef fun predecessor(i) is intern
 589
 590         redef fun distance(c)
 591         do
 592                 var d = self.ascii - c.ascii
 593                 if d >= 0 then
 594                         return d
 595                 else
 596                         return -d
 597                 end
 598         end
 599
 600         # If `self` is a digit then return this digit else return -1.
 601         #
 602         #     assert '5'.to_i    == 5
 603         fun to_i: Int
 604         do
 605
 606                 if self == '-' then
 607                         return -1
 608                 else if is_digit then
 609                         return self.ascii - '0'.ascii
 610                 else
 611                         return self.to_lower.ascii - 'a'.ascii + 10
 612                 end
 613         end
 614
 615         # the ascii value of self
 616         #
 617         #     assert 'a'.ascii    == 97
 618         #     assert '\n'.ascii   == 10
 619         fun ascii: Int is intern
 620
 621         # Return the lower case version of self.
 622         # If self is not a letter, then return self
 623         #
 624         #     assert 'A'.to_lower  == 'a'
 625         #     assert 'a'.to_lower  == 'a'
 626         #     assert '$'.to_lower  == '$'
 627         fun to_lower: Char
 628         do
 629                 if is_upper then
 630                         return (ascii + ('a'.distance('A'))).ascii
 631                 else
 632                         return self
 633                 end
 634         end
 635
 636         # Return the upper case version of self.
 637         # If self is not a letter, then return self
 638         #
 639         #     assert 'a'.to_upper  == 'A'
 640         #     assert 'A'.to_upper  == 'A'
 641         #     assert '$'.to_upper  == '$'
 642         fun to_upper: Char
 643         do
 644                 if is_lower then
 645                         return (ascii - ('a'.distance('A'))).ascii
 646                 else
 647                         return self
 648                 end
 649         end
 650
 651         # Is self a digit? (from '0' to '9')
 652         #
 653         #     assert '0'.is_digit   == true
 654         #     assert '9'.is_digit   == true
 655         #     assert 'a'.is_digit   == false
 656         fun is_digit : Bool
 657         do
 658                 return self >= '0' and self <= '9'
 659         end
 660
 661         # Is self a lower case letter? (from 'a' to 'z')
 662         #
 663         #     assert 'a'.is_lower   == true
 664         #     assert 'z'.is_lower   == true
 665         #     assert 'A'.is_lower   == false
 666         #     assert '$'.is_lower   == false
 667         fun is_lower : Bool
 668         do
 669                 return self >= 'a' and self <= 'z'
 670         end
 671
 672         # Is self a upper case letter? (from 'A' to 'Z')
 673         #
 674         #     assert 'A'.is_upper   == true
 675         #     assert 'A'.is_upper   == true
 676         #     assert 'z'.is_upper   == false
 677         #     assert '$'.is_upper   == false
 678         fun is_upper : Bool
 679         do
 680                 return self >= 'A' and self <= 'Z'
 681         end
 682
 683         # Is self a letter? (from 'A' to 'Z' and 'a' to 'z')
 684         #
 685         #     assert 'A'.is_letter  == true
 686         #     assert 'A'.is_letter  == true
 687         #     assert 'z'.is_letter  == true
 688         #     assert '$'.is_letter  == false
 689         fun is_letter : Bool
 690         do
 691                 return is_lower or is_upper
 692         end
 693 end
 694
 695 # Pointer classes are used to manipulate extern C structures.
 696 extern class Pointer
 697         # Is the address behind this Object at NULL?
 698         fun address_is_null: Bool is extern "address_is_null"
 699
 700         # Free the memory pointed by this pointer
 701         fun free `{ free(recv); `}
 702 end