-------- SIMTEL20 Ada Software Repository Prologue ------------
--                                                           -*
-- Unit name    : Bit_Functions
-- Version      : 1.0
-- Author       : Freeman L. Moore
--              : P.O. Box 801 M/S 8006
--              : Texas Instruments, Inc.
--              : McKinney, Texas   75069
-- DDN Address  : FMOORE%TI-EG@CSNET-RELAY
-- Copyright    : (c) 1985
-- Date created : February 1985
-- Release date : June 1985
-- Last update  : June 1985
-- Machine/System Compiled/Run on :
--                DG MV/1000, Rolm/ADE version 2.20          -*
---------------------------------------------------------------
--                                                           -*
-- Keywords     : bit functions, shifting, masks
----------------:
--
-- Abstract     : This package represents a collection of
----------------: routines which allow the Ada programmer
--              : the ability of perform bit operations on
--              : objects of type INTEGER.  The functions
--              : include the ability to extract/insert bit
--              : fields, shift objects left or right,
--              : and/or objects and create bit masks.
--              :
--                                                           -*
------------------ Revision history ---------------------------
--                                                           -*
-- DATE         VERSION AUTHOR                  HISTORY
-- Feb 85        1.0    Freeman Moore           original
--                                                           -*
------------------ Distribution and Copyright -----------------
--                                                           -*
-- This prologue must be included in all copies of this software.
--
-- This software is copyright by the author.
--
-- This software is released to the Ada community.
-- This software is released to the Public Domain (note:
--   software released to the Public Domain is not subject
--   to copyright protection).
-- Restrictions on use or distribution:  NONE
--                                                           -*
------------------ Disclaimer ---------------------------------
--                                                           -*
-- This software and its documentation are provided "AS IS" and
-- without any expressed or implied warranties whatsoever.
-- No warranties as to performance, merchantability, or fitness
-- for a particular purpose exist.
--
-- Because of the diversity of conditions and hardware under
-- which this software may be used, no warranty of fitness for
-- a particular purpose is offered.  The user is advised to
-- test the software thoroughly before relying on it.  The user
-- must assume the entire risk and liability of using this
-- software.
--
-- In no event shall any person or organization of people be
-- held responsible for any direct, indirect, consequential
-- or inconsequential damages or lost profits.

--                                                           -*
-------------------END-PROLOGUE--------------------------------
package Bit_Functions is
    --
    --   This package allows the Ada programmer to manipulate the bits
    --   within an object of type INTEGER.  The bits are numbers from
    --   the right to the left, starting with number zero.
    --
    --           +------------------------+
    --           +  15 14 13 ...  3 2 1 0 !
    --           +------------------------+
    --
    --      In each routine, the number of bits being manipulated
    --      is NBITS.  START_AT identifies the right most bit of NBITS field.
    --
    --      e.g.
    --           ...  6 5 4 3 2 1 0
    --                    X X X         nbits = 3
    --                                  start_at = 2
    --
    --
    function Bit_Extract (Item, Start_At, Nbits : Integer) return Integer;
    --      Return the bit field extracted from ITEM, as a signed integer;
    --
    function Ubit_Extract (Item, Start_At, Nbits : Integer) return Integer;
    --      return the bit field extracted from ITEM, unsigned integer;
    --
    function Bit_Insert (This_Item, Nbits, Into_Item, Start_At : Integer)
                        return Integer;
    --      insert NBITS from THIS_ITEM into the object INTO_ITEM,
    --      with the rightmost bit identified by START_AT.
    --
    function Bit_Remove (Item, Start_At, Nbits : Integer) return Integer;
    --      BIT_REMOVE will zero out NBITS of ITEM at position START_AT
    --
    function Shift_Left (Item, Nbits : Integer) return Integer;
    --      return ITEM shifted left by NBITS
    --
    function Shift_Right (Item, Nbits : Integer) return Integer;
    --      return ITEM shifted right by NBITS
    --
    function Bit_And (Word1, Word2 : Integer) return Integer;
    --      return the AND of the two objects
    --
    function Bit_Or (Word1, Word2 : Integer) return Integer;
    --      return the OR of the two objects
    --
    function Bit_Mask (Nbits : Integer) return Integer;
    --      return an object with NBITS of one bits, right justified
    --
end Bit_Functions;