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