builtin.nim

## The MIT License (MIT)
##
## Copyright (c) 2016 Rokas Kupstys
## Copyright (C) 2014-2016 Quinten Lansu
## Copyright (C) 2006-2015 Andreas Rumpf and other contributors
##
## Permission is hereby granted, free of charge, to any person obtaining a copy
## of this software and associated documentation files (the "Software"), to deal
## in the Software without restriction, including without limitation the rights
## to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
## copies of the Software, and to permit persons to whom the Software is
## furnished to do so, subject to the following conditions:
##
## The above copyright notice and this permission notice shall be included in
## all copies or substantial portions of the Software.
##
## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
## IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
## FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
## AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
## LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
## OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
## SOFTWARE.

# iterator count*(start, stop, step: int): int {.inline.} =
#     ## Yields integers in range [``start``, ``stop``) incrementing number by ``step``.
#     var i = start
#     while i != stop:
#         yield i
#         i += step

# template count*(start, stop: int) {.dirty.} = count(start, stop, if start < stop: 1 else: -1)
#     ## Yields integers in range [``start``, ``stop``) incrementing number by 1 if ``start`` < ``stop``
#     ## or decrementing number by 1 if ``start`` > ``stop``.

# template count*(stop: int)        {.dirty.} = count(0,     stop, if stop  >    0: 1 else: -1)
#     ## Yields integers in range [0, ``stop``) incrementing or decrementing number by 1.

# iterator enumerate*[T1, T2](iterable: T1): tuple[key: int, value: T2] =
#     ## Yields ``tuple(key, value)`` where key is index of value in iterable. Iterable must support
#     ## ``len()`` and ``[]``.
#     var i = 0
#     while i < iterable.len:
#         yield (i, iterable[i])
#         i += 1


proc `<<` *[T: SomeInteger](x, y: T): T {.magic: "ShlI", noSideEffect.}
    ## Left shift operator for integers

proc `>>`*[T: SomeInteger](x, y: T): T {.magic: "ShrI", noSideEffect.}
    ## Right shift operator for integers

proc `%` *[T: SomeInteger](x, y: T): T {.magic: "ModU", noSideEffect.}
    ## Modulus operator for integers

proc `&`*[T: SomeInteger](x, y: T): T {.magic: "BitandI", noSideEffect.}
    ## Bitwise "and" operator for integers

proc `|` *[T: SomeInteger](x, y: T): T {.magic: "BitorI", noSideEffect.}
    ## Bitwise "or" operator for integers

proc `xor` *(x, y: char): char {.magic: "BitxorI", noSideEffect.}
    ## "xor" operator for chars

proc `++`*[T: SomeInteger|enum|bool](x: var T) = inc(x)
    ## Increments ``x`` by 1

proc `--`*[T: SomeInteger|enum|bool](x: var T) = dec(x)
    ## Decrements ``x`` by 1

proc memzero*(p: pointer, size: Natural) {.inline.} = zero_mem(p, size)
    ## overwrites the contents of the memory at ``p`` with the value 0.
    ## Exactly ``size`` bytes will be overwritten. Like any procedure
    ## dealing with raw memory this is *unsafe*.

proc memcpy*(dest, source: pointer, size: Natural) {.inline.} = copy_mem(dest, source, size)
    ## copies the contents from the memory at ``source`` to the memory
    ## at ``dest``. Exactly ``size`` bytes will be copied. The memory
    ## regions may not overlap. Like any procedure dealing with raw
    ## memory this is *unsafe*.

proc memmove*(dest, source: pointer, size: Natural) {.inline.} = move_mem(dest, source, size)
    ## copies the contents from the memory at ``source`` to the memory
    ## at ``dest``. Exactly ``size`` bytes will be copied. The memory
    ## regions may overlap, ``moveMem`` handles this case appropriately
    ## and is thus somewhat more safe than ``copyMem``. Like any procedure
    ## dealing with raw memory this is still *unsafe*, though.

proc memeq*(a, b: pointer, size: Natural): bool = equal_mem(a, b, size)
    ## compares the memory blocks ``a`` and ``b``. ``size`` bytes will
    ## be compared. If the blocks are equal, true is returned, false
    ## otherwise. Like any procedure dealing with raw memory this is
    ## *unsafe*.

# exceptions
proc new*[T: Exception](_: typedesc[T], msg: string=""): ref T =
    return (ref T)(msg: msg)

proc new*[T: OSError | LibraryError](_: typedesc[T], msg: string="", error_code: int=0): ref T =
    return (ref T)(msg: msg, error_code: error_code)