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
 418         # Modulo of `self` with `i`.
 419         #
 420         # Finds the remainder of division of `self` by `i`.
 421         #
 422         #     assert 5 % 2                      == 1
 423         #     assert 10 % 2                     == 0
 424         fun %(i: Int): Int is intern
 425
 426         redef fun zero do return 0
 427         redef fun value_of(val) do return val.to_i
 428
 429         # `i` bits shift fo the left (aka <<)
 430         #
 431         #     assert 5.lshift(1)    == 10
 432         fun lshift(i: Int): Int is intern
 433
 434         # `i` bits shift fo the right (aka >>)
 435         #
 436         #     assert 5.rshift(1)    == 2
 437         fun rshift(i: Int): Int is intern
 438
 439         redef fun to_i do return self
 440         redef fun to_f is intern
 441
 442         redef fun distance(i)
 443         do
 444                 var d = self - i
 445                 if d >= 0 then
 446                         return d
 447                 else
 448                         return -d
 449                 end
 450         end
 451
 452         redef fun <=>(other)
 453         do
 454                 if self < other then
 455                         return -1
 456                 else if other < self then
 457                         return 1
 458                 else
 459                         return 0
 460                 end
 461         end
 462
 463         redef fun is_between(c, d)
 464         do
 465                 if self < c or d < self then
 466                         return false
 467                 else
 468                         return true
 469                 end
 470         end
 471
 472         redef fun max(other)
 473         do
 474                 if self < other then
 475                         return other
 476                 else
 477                         return self
 478                 end
 479         end
 480
 481         redef fun min(c)
 482         do
 483                 if c < self then
 484                         return c
 485                 else
 486                         return self
 487                 end
 488         end
 489
 490         # The character whose ASCII value is `self`.
 491         #
 492         #      assert 65.ascii   == 'A'
 493         #      assert 10.ascii   == '\n'
 494         fun ascii: Char is intern
 495
 496         # Number of digits of an integer in base `b` (plus one if negative)
 497         #
 498         #     assert 123.digit_count(10) == 3
 499         #     assert 123.digit_count(2) == 7 # 1111011 in binary
 500         fun digit_count(b: Int): Int
 501         do
 502                 if b == 10 then return digit_count_base_10
 503                 var d: Int # number of digits
 504                 var n: Int # current number
 505                 # Sign
 506                 if self < 0 then
 507                         d = 1
 508                         n = - self
 509                 else if self == 0 then
 510                         return 1
 511                 else
 512                         d = 0
 513                         n = self
 514                 end
 515                 # count digits
 516                 while n > 0 do
 517                         d += 1
 518                         n = n / b       # euclidian division /
 519                 end
 520                 return d
 521         end
 522
 523         # Optimized version for base 10
 524         fun digit_count_base_10: Int
 525         do
 526                 var val: Int
 527                 var result: Int
 528                 if self < 0 then
 529                         result = 2
 530                         val = -self
 531                 else
 532                         result = 1
 533                         val = self
 534                 end
 535                 loop
 536                         if val < 10 then return result
 537                         if val < 100 then return result+1
 538                         if val < 1000 then return result+2
 539                         if val < 10000 then return result+3
 540                         val = val / 10000
 541                         result += 4
 542                 end
 543         end
 544
 545         # Return the corresponding digit character
 546         # If 0 <= `self` <= 9, return the corresponding character.
 547         #     assert 5.to_c    == '5'
 548         # If 10 <= `self` <= 36, return the corresponding letter [a..z].
 549         #     assert 15.to_c   == 'f'
 550         fun to_c: Char
 551         do
 552                 assert self >= 0 and self <= 36 # TODO plan for this
 553                 if self < 10 then
 554                         return (self + '0'.ascii).ascii
 555                 else
 556                         return (self + ('a'.ascii - 10)).ascii
 557                 end
 558         end
 559
 560         # The absolute value of self
 561         #
 562         #     assert (-10).abs   == 10
 563         #     assert 10.abs    == 10
 564         #     assert 0.abs     == 0
 565         fun abs: Int
 566         do
 567             if self >= 0
 568             then
 569                 return self
 570             else
 571                 return -1 * self
 572             end
 573         end
 574 end
 575
 576 # Native characters.
 577 # Characters are denoted with simple quote.
 578 # eg. `'a'` or `'\n'`.
 579 universal Char
 580         super Discrete
 581         redef type OTHER: Char
 582
 583         redef fun object_id is intern
 584         redef fun hash do return ascii
 585         redef fun ==(o) is intern
 586         redef fun !=(o) is intern
 587         redef fun output is intern
 588
 589         redef fun <=(i) is intern
 590         redef fun <(i) is intern
 591         redef fun >=(i) is intern
 592         redef fun >(i) is intern
 593
 594         redef fun successor(i) is intern
 595         redef fun predecessor(i) is intern
 596
 597         redef fun distance(c)
 598         do
 599                 var d = self.ascii - c.ascii
 600                 if d >= 0 then
 601                         return d
 602                 else
 603                         return -d
 604                 end
 605         end
 606
 607         # If `self` is a digit then return this digit else return -1.
 608         #
 609         #     assert '5'.to_i    == 5
 610         fun to_i: Int
 611         do
 612
 613                 if self == '-' then
 614                         return -1
 615                 else if is_digit then
 616                         return self.ascii - '0'.ascii
 617                 else
 618                         return self.to_lower.ascii - 'a'.ascii + 10
 619                 end
 620         end
 621
 622         # the ascii value of self
 623         #
 624         #     assert 'a'.ascii    == 97
 625         #     assert '\n'.ascii   == 10
 626         fun ascii: Int is intern
 627
 628         # Return the lower case version of self.
 629         # If self is not a letter, then return self
 630         #
 631         #     assert 'A'.to_lower  == 'a'
 632         #     assert 'a'.to_lower  == 'a'
 633         #     assert '$'.to_lower  == '$'
 634         fun to_lower: Char
 635         do
 636                 if is_upper then
 637                         return (ascii + ('a'.distance('A'))).ascii
 638                 else
 639                         return self
 640                 end
 641         end
 642
 643         # Return the upper case version of self.
 644         # If self is not a letter, then return self
 645         #
 646         #     assert 'a'.to_upper  == 'A'
 647         #     assert 'A'.to_upper  == 'A'
 648         #     assert '$'.to_upper  == '$'
 649         fun to_upper: Char
 650         do
 651                 if is_lower then
 652                         return (ascii - ('a'.distance('A'))).ascii
 653                 else
 654                         return self
 655                 end
 656         end
 657
 658         # Is self a digit? (from '0' to '9')
 659         #
 660         #     assert '0'.is_digit   == true
 661         #     assert '9'.is_digit   == true
 662         #     assert 'a'.is_digit   == false
 663         fun is_digit : Bool
 664         do
 665                 return self >= '0' and self <= '9'
 666         end
 667
 668         # Is self a lower case letter? (from 'a' to 'z')
 669         #
 670         #     assert 'a'.is_lower   == true
 671         #     assert 'z'.is_lower   == true
 672         #     assert 'A'.is_lower   == false
 673         #     assert '$'.is_lower   == false
 674         fun is_lower : Bool
 675         do
 676                 return self >= 'a' and self <= 'z'
 677         end
 678
 679         # Is self a upper case letter? (from 'A' to 'Z')
 680         #
 681         #     assert 'A'.is_upper   == true
 682         #     assert 'A'.is_upper   == true
 683         #     assert 'z'.is_upper   == false
 684         #     assert '$'.is_upper   == false
 685         fun is_upper : Bool
 686         do
 687                 return self >= 'A' and self <= 'Z'
 688         end
 689
 690         # Is self a letter? (from 'A' to 'Z' and 'a' to 'z')
 691         #
 692         #     assert 'A'.is_letter  == true
 693         #     assert 'A'.is_letter  == true
 694         #     assert 'z'.is_letter  == true
 695         #     assert '$'.is_letter  == false
 696         fun is_letter : Bool
 697         do
 698                 return is_lower or is_upper
 699         end
 700 end
 701
 702 # Pointer classes are used to manipulate extern C structures.
 703 extern class Pointer
 704         # Is the address behind this Object at NULL?
 705         fun address_is_null: Bool is extern "address_is_null"
 706
 707         # Free the memory pointed by this pointer
 708         fun free `{ free(recv); `}
 709 end