Next: , Previous: uint32, Up: Top   [Contents]


118 uint64

%--------------------------------------------------%
% vim: ts=4 sw=4 et ft=mercury
%--------------------------------------------------%
% Copyright (C) 2018-2021 The Mercury team.
% This file is distributed under the terms specified in COPYING.LIB.
%--------------------------------------------------%
%
% File: uint64.m
% Main author: juliensf
% Stability: low.
%
% Predicates and functions for dealing with unsigned 64-bit integer numbers.
%
%--------------------------------------------------%

:- module uint64.
:- interface.

:- import_module pretty_printer.

%--------------------------------------------------%
%
% Conversion from int.
%

    % from_int(I, U64):
    %
    % Convert an int into a uint64.
    % Fails if I is not in [0, 2^64 - 1].
    %
:- pred from_int(int::in, uint64::out) is semidet.

    % det_from_int(I) = U64:
    %
    % Convert an int into a uint64.
    % Throws an exception if I is not in [0, 2^64 - 1].
    %
:- func det_from_int(int) = uint64.

    % cast_from_int(I) = U64:
    %
    % Convert an int to a uint64.
    % Always succeeds, but will yield a result that is mathematically equal
    % to I only if I is in [0, 2^64 - 1].
    %
:- func cast_from_int(int) = uint64.

%--------------------------------------------------%
%
% Conversion from uint.
%

    % cast_from_uint(U) = U64:
    %
    % Convert a uint to a uint64.
    % Always succeeds, and will always yield a result that is
    % mathematically equal U.
    %
:- func cast_from_uint(uint) = uint64.

%--------------------------------------------------%
%
% Conversion to int.
%

    % cast_to_int(U64) = I:
    %
    % Convert a uint64 to an int.
    % Always succeeds. If ints are 64 bits, I will be mathematically
    % equal to U64 only if U64 is in [0, 2^63 - 1]. If ints are 32
    % bits, I will be mathematically equal to U64 only if U64 is in
    % [0, 2^31 - 1].
    %
:- func cast_to_int(uint64) = int.

%--------------------------------------------------%
%
% Conversion to uint.
%

    % cast_to_uint(U64) = U:
    %
    % Convert a uint64 to a uint.
    % Always succeeds, but will yield a result that is mathematically equal
    % to U64 only if uints are 64 bits.
    %
:- func cast_to_uint(uint64) = uint.

%--------------------------------------------------%
%
% Conversion to/from uint8
%

    % cast_to_uint8(U64) = U8:
    %
    % Convert a uint64 to a uint8.
    % Always succeeds, but will yield a result that is mathematically equal
    % to U64 only if U64 is in [0, 2^8 - 1].
    %
:- func cast_to_uint8(uint64) = uint8.

    % cast_from_uint8(U8) = U64:
    %
    % Convert a uint8 to a uint64.
    % Always succeeds, and yields a result that is mathematically equal
    % to U8.
    %
:- func cast_from_uint8(uint8) = uint64.

%--------------------------------------------------%
%
% Change of signedness.
%

    % cast_from_int64(I64) = U64:
    %
    % Convert an int64 to a uint64. This will yield a result that is
    % mathematically equal to I64 only if I64 is in [0, 2^63 - 1].
    %
:- func cast_from_int64(int64) = uint64.

%--------------------------------------------------%
%
% Conversion from byte sequence.
%

    % from_bytes_le(Byte0, Byte1, ..., Byte7) = U64:
    %
    % U64 is the uint64 whose bytes are given in little-endian order by the
    % arguments from left-to-right (i.e. Byte0 is the least significant byte
    % and Byte7 is the most significant byte).
    %
:- func from_bytes_le(uint8, uint8, uint8, uint8, uint8, uint8, uint8, uint8)
    = uint64.

    % from_bytes_be(Byte0, Byte1, ..., Byte7) = U64:
    %
    % U64 is the uint64 whose bytes are given in big-endian order by the
    % arguments in left-to-right order (i.e. Byte0 is the most significant
    % byte and Byte7 is the least significant byte).
    %
:- func from_bytes_be(uint8, uint8, uint8, uint8, uint8, uint8, uint8, uint8)
    = uint64.

%--------------------------------------------------%
%
% Comparisons and related operations.
%

    % Less than.
    %
:- pred (uint64::in) < (uint64::in) is semidet.

    % Greater than.
    %
:- pred (uint64::in) > (uint64::in) is semidet.

    % Less than or equal.
    %
:- pred (uint64::in) =< (uint64::in) is semidet.

    % Greater than or equal.
    %
:- pred (uint64::in) >= (uint64::in) is semidet.

    % Maximum.
    %
:- func max(uint64, uint64) = uint64.

    % Minimum.
    %
:- func min(uint64, uint64) = uint64.

%--------------------------------------------------%
%
% Arithmetic operations.
%

    % Addition.
    %
:- func uint64 + uint64 = uint64.
:- mode in + in = uo is det.
:- mode uo + in = in is det.
:- mode in + uo = in is det.

:- func plus(uint64, uint64) = uint64.

    % Subtraction.
    %
:- func uint64 - uint64 = uint64.
:- mode in - in = uo is det.
:- mode uo - in = in is det.
:- mode in - uo = in is det.

:- func minus(uint64, uint64) = uint64.

    % Multiplication.
    %
:- func (uint64::in) * (uint64::in) = (uint64::uo) is det.
:- func times(uint64, uint64) = uint64.

    % Truncating integer division.
    %
    % Throws a `domain_error' exception if the right operand is zero.
    %
:- func (uint64::in) div (uint64::in) = (uint64::uo) is det.

    % Truncating integer division.
    %
    % Throws a `domain_error' exception if the right operand is zero.
    %
:- func (uint64::in) // (uint64::in) = (uint64::uo) is det.

    % (/)/2 is a synonym for (//)/2.
    %
:- func (uint64::in) / (uint64::in) = (uint64::uo) is det.

    % unchecked_quotient(X, Y) is the same as X // Y, but the behaviour
    % is undefined if the right operand is zero.
    %
:- func unchecked_quotient(uint64::in, uint64::in) = (uint64::uo) is det.

    % Modulus.
    % X mod Y = X - (X div Y) * Y
    %
    % Throws a `domain_error' exception if the right operand is zero.
    %
:- func (uint64::in) mod (uint64::in) = (uint64::uo) is det.

    % Remainder.
    % X rem Y = X - (X // Y) * Y.
    %
    % Throws a `domain_error/` exception if the right operand is zero.
    %
:- func (uint64::in) rem (uint64::in) = (uint64::uo) is det.

    % unchecked_rem(X, Y) is the same as X rem Y, but the behaviour is
    % undefined if the right operand is zero.
    %
:- func unchecked_rem(uint64::in, uint64::in) = (uint64::uo) is det.

    % even(X) is equivalent to (X mod 2 = 0).
    %
:- pred even(uint64::in) is semidet.

    % odd(X) is equivalent to (not even(X)), i.e. (X mod 2 = 1).
    %
:- pred odd(uint64::in) is semidet.

%--------------------------------------------------%
%
% Shift operations.
%

    % Left shift.
    % X << Y returns X "left shifted" by Y bits.
    % The bit positions vacated by the shift are filled by zeros.
    % Throws an exception if Y is not in [0, 64).
    %
:- func (uint64::in) << (int::in) = (uint64::uo) is det.
:- func (uint64::in) <<u (uint::in) = (uint64::uo) is det.

    % unchecked_left_shift(X, Y) is the same as X << Y except that
    % the behaviour is undefined if Y is not in [0, 64).
    % It will typically be implemented more efficiently than X << Y.
    %
:- func unchecked_left_shift(uint64::in, int::in) = (uint64::uo) is det.
:- func unchecked_left_ushift(uint64::in, uint::in) = (uint64::uo) is det.

    % Right shift.
    % X >> Y returns X "right shifted" by Y bits.
    % The bit positions vacated by the shift are filled by zeros.
    % Throws an exception if Y is not in [0, 64).
    %
:- func (uint64::in) >> (int::in) = (uint64::uo) is det.
:- func (uint64::in) >>u (uint::in) = (uint64::uo) is det.

    % unchecked_right_shift(X, Y) is the same as X >> Y except that
    % the behaviour is undefined if Y is not in [0, 64).
    % It will typically be implemented more efficiently than X >> Y.
    %
:- func unchecked_right_shift(uint64::in, int::in) = (uint64::uo) is det.
:- func unchecked_right_ushift(uint64::in, uint::in) = (uint64::uo) is det.

%--------------------------------------------------%
%
% Logical operations.
%

    % Bitwise and.
    %
:- func (uint64::in) /\ (uint64::in) = (uint64::uo) is det.

    % Bitwise or.
    %
:- func (uint64::in) \/ (uint64::in) = (uint64::uo) is det.

    % Bitwise exclusive or (xor).
    %
:- func xor(uint64, uint64) = uint64.
:- mode xor(in, in) = uo is det.
:- mode xor(in, uo) = in is det.
:- mode xor(uo, in) = in is det.

    % Bitwise complement.
    %
:- func \ (uint64::in) = (uint64::uo) is det.

%--------------------------------------------------%
%
% Operations on bits and bytes.
%

    % num_zeros(U) = N:
    %
    % N is the number of zeros in the binary representation of U.
    %
:- func num_zeros(uint64) = int.

    % num_ones(U) = N:
    %
    % N is the number of ones in the binary representation of U.
    %
:- func num_ones(uint64) = int.

    % num_leading_zeros(U) = N:
    %
    % N is the number of leading zeros in the binary representation of U.
    %
:- func num_leading_zeros(uint64) = int.

    % num_trailing_zeros(U) = N:
    % N is the number of trailing zeros in the binary representation of U.
    %
:- func num_trailing_zeros(uint64) = int.

    % reverse_bytes(A) = B:
    %
    % B is the value that results from reversing the bytes in the binary
    % representation of A.
    %
:- func reverse_bytes(uint64) = uint64.

    % reverse_bits(A) = B:
    %
    % B is the is value that results from reversing the bits
    % in the binary representation of A.
    %
:- func reverse_bits(uint64) = uint64.

    % rotate_left(U, D) = N:
    %
    % N is the value obtained by rotating the binary representation of U
    % left by D bits. Throws an exception if D is not in the range [0, 63].
    %
:- func rotate_left(uint64, uint) = uint64.

    % unchecked_rotate_left(U, D) = N:
    %
    % N is the value obtained by rotating the binary representation of U
    % left by an amount given by the lowest 6 bits of D.
    %
:- func unchecked_rotate_left(uint64, uint) = uint64.

    % rotate_right(U, D) = N:
    %
    % N is the value obtained by rotating the binary representation of U
    % right by D bits. Throws an exception if D is not in the range [0, 63].
    %
:- func rotate_right(uint64, uint) = uint64.

    % unchecked_rotate_left(U, D) = N:
    %
    % N is the value obtained by rotating the binary representation of U
    % right by an amount given by the lowest 6 bits of D.
    %
:- func unchecked_rotate_right(uint64, uint) = uint64.

    % set_bit(U, I) = N:
    % N is the value obtained by setting the I'th bit (the bit worth 2^I) of U
    % to one. An exception is thrown if I is not in the range [0, 63].
    %
:- func set_bit(uint64, uint) = uint64.

    % unchecked_set_bit(U, I) = N:
    % As above, but the behaviour is undefined if I is not in the range
    % [0, 63].
    %
:- func unchecked_set_bit(uint64, uint) = uint64.

    % clear_bit(U, I) = N:
    % N is the value obtained by setting the I'th bit (the bit worth 2^I) of U
    % to zero. An exception is thrown if I is not in the range [0, 63].
    %
:- func clear_bit(uint64, uint) = uint64.

    % unchecked_clear_bit(U, I) = N:
    % As above, but the behaviour is undefined if I is not in the range
    % [0, 63].
    %
:- func unchecked_clear_bit(uint64, uint) = uint64.

    % flip_bit(U, I) = N:
    % N is the value obtained by flipping the I'th bit (the bit worth 2^I) of
    % U. An exception is thrown if I is not in the range [0, 63].
    %
:- func flip_bit(uint64, uint) = uint64.

    % unchecked_flip_bit(U, I) = N:
    % As above, but the behaviour is undefined if I is not in the range
    % [0, 63].
    %
:- func unchecked_flip_bit(uint64, uint) = uint64.

    % bit_is_set(U, I):
    % True iff the I'th bit (the bit worth 2^I) of U is one.
    % An exception is thrown if I is not in the range [0, 63].
    %
:- pred bit_is_set(uint64::in, uint::in) is semidet.

    % unchecked_bit_is_set(U, I):
    % As above, but the behaviour is undefined if I is not in the range
    % [0, 63].
    %
:- pred unchecked_bit_is_set(uint64::in, uint::in) is semidet.

    % bit_is_clear(U, I):
    % True iff the I'th bit (the bit worth 2^I) of U is zero.
    % An exception is thrown if I is not in the range [0, 63].
    %
:- pred bit_is_clear(uint64::in, uint::in) is semidet.

    % unchecked_bit_is_clear(U, I):
    % As above, but the behaviour is undefined if I is not in the range
    % [0, 63].
    %
:- pred unchecked_bit_is_clear(uint64::in, uint::in) is semidet.

%--------------------------------------------------%
%
% Limits.
%

:- func max_uint64 = uint64.

%--------------------------------------------------%
%
% Prettyprinting.
%

    % Convert a uint64 to a pretty_printer.doc for formatting.
    %
:- func uint64_to_doc(uint64) = pretty_printer.doc.
:- pragma obsolete(func(uint64_to_doc/1), [pretty_printer.uint64_to_doc/1]).

%--------------------------------------------------%
%--------------------------------------------------%


Next: , Previous: uint32, Up: Top   [Contents]