Name

---

      BIT_EXTRACT

Purpose

---

      Extract a specified bit string from a byte array.

Category

---

Calling Sequence

---

      out = bit_extract(inbytes,b1,b2,[nwrds])

Inputs

---

      inbytes = Byte array to extract bits from. in
        1-D or 2-D.
      b1 = Start bit of bit string. in
      b2 = End bit of bit string. in
        The bit address can range up to the total
        number of bits in the byte array.
      nwrds = Optional number of words (def=1). in
        Number of equal size bit strings from b1 to b2.
        nwrds must go evenly into the number of bits
        from b1 to b2.

Keyword Parameters

---

Keywords

---

        /ONE means bit addresses start at 1, else 0.
        /BYTES Return right justified bit string in
          a byte array even if it has less than 64 bits.
          Only the number of bytes needed to contain the
          bit string are returned. Normally an integer
          value is returned if it can hold the value.
        DESCRIPTION=txt Text array describing the bits in the
          given byte array. When this is given the items listed
          in txt are extracted and out is returned as a structure.
          Each line in txt describes one extracted item and
          has FOUR required parts (separated by whitespace):
              tag b1 b2 nwds [optional text]
          Tag is the name that will be used in the structure and
          b1 and b2 are the start and end bit in the byte array.
          nwds is the number of words in the returned item.
          The bits/word = (b2-b1+1)/nwds.
        ERROR=err Error flag: 0=ok.

Outputs

---

      out = Returned extracted bit string. out
        Normally an unsigned integer but will be
        a byte array if more than 64 bits or if
        the keyword /BYTES is used.
        If the keyword DESCRIPTION is used then out will
        be a structure containing the items described.

Common Blocks

---

      bit_extract_com

Notes

---

      Notes: b1 is the most significant bit (MSB) or the
      bit string, b2 is the least significant bit (LSB).
      When extracting from a 2-D byte array b1 and b2
      are bit addresses in the X dimension of the array,
      and columns of bit strings are extracted. Extracted
      bit strings are returned as unsigned integers big
      enough to contain the bit string.

Modification History

---

      R. Sterner, 2011 Aug 23
      R. Sterner, 2011 Sep 01 --- Added keyword DESCRIPTION.
      R. Sterner, 2011 Sep 05 --- Was initializing common every time. Fixed.
      R. Sterner, 2011 Sep 06 --- Added nwords as input.
      R. Sterner, 2011 Sep 06 --- Fixed forced byte array for all records.
      R. Sterner, 2011 Sep 06 --- Added bit string array handling.
      R. Sterner, 2011 Sep 19 --- Returned an error flag instead of stopping.
      R. Sterner, 2011 Sep 19 --- Added bit_unpack when nwrds GT 1.
      R. Sterner, 2011 Sep 28 --- More detailed error message for recursive.
      R. Sterner, 2012 Jul 27 --- Made /BYTES work for bit arrays.
  Copyright (C) 2011, Johns Hopkins University/Applied Physics Laboratory
  This software may be used, copied, or redistributed as long as it is not
  sold and this copyright notice is reproduced on each copy made. This
  routine is provided as is without any express or implied warranties
  whatsoever. Other limitations apply as described in the file disclaimer.txt.