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