harbour-core/harbour/doc/en/binnum.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 2000 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: BIN2W(), BIN2I(), BIN2L(), BIN2U(), I2BIN(), W2BIN(),
 *                       L2BIN(), U2BIN()
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      BIN2W()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert unsigned short encoded bytes into Harbour numeric
 *  $SYNTAX$
 *      BIN2W( <cBuffer> ) --> nNumber
 *  $ARGUMENTS$
 *      <cBuffer> is a character string that contain 16 bit encoded unsigned
 *      short integer (least significant byte first). The first two bytes
 *      are taken into account, the rest if any are ignored.
 *  $RETURNS$
 *      BIN2W() return numeric integer (or 0 if <cBuffer> is not a string).
 *  $DESCRIPTION$
 *      BIN2W() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. BIN2W() take two bytes of encoded
 *      16 bit unsigned short integer and convert it into standard Harbour
 *      numeric value.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      BIN2W() is the opposite of W2BIN()
 *  $EXAMPLES$
 *      // Show header length of a DBF
 *      FUNCTION main()
 *      LOCAL nHandle, cBuffer := space( 2 )
 *      nHandle := fopen( "test.dbf" )
 *      IF nHandle > 0
 *         fseek( nHandle, 8 )
 *         fread( nHandle, @cBuffer, 2 )
 *         ? "Length of DBF header in bytes:", BIN2W( cBuffer )
 *         fclose( nHandle )
 *      ELSE
 *         ? "Can not open file"
 *      ENDIF
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2U(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(),FREAD()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      BIN2I()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert signed short encoded bytes into Harbour numeric
 *  $SYNTAX$
 *      BIN2I( <cBuffer> ) --> nNumber
 *  $ARGUMENTS$
 *      <cBuffer> is a character string that contain 16 bit encoded signed
 *      short integer (least significant byte first). The first two bytes
 *      are taken into account, the rest if any are ignored.
 *  $RETURNS$
 *      BIN2I() return numeric integer (or 0 if <cBuffer> is not a string).
 *  $DESCRIPTION$
 *      BIN2I() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. BIN2I() take two bytes of encoded
 *      16 bit signed short integer and convert it into standard Harbour
 *      numeric value.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      BIN2I() is the opposite of I2BIN()
 *  $EXAMPLES$
 *      // Show DBF last update date
 *      FUNCTION main()
 *      LOCAL nHandle, cYear, cMonth, cDay
 *      nHandle := fopen( "test.dbf" )
 *      IF nHandle > 0
 *         fseek( nHandle, 1 )
 *         cYear := cMonth := cDay := " "
 *         fread( nHandle, @cYear , 1 )
 *         fread( nHandle, @cMonth, 1 )
 *         fread( nHandle, @cDay  , 1 )
 *         ? "Last update:", BIN2I( cYear ), BIN2I( cMonth ), BIN2I( cDay )
 *         fclose( nHandle )
 *      ELSE
 *         ? "Can not open file"
 *      ENDIF
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2L(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(),FREAD()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      BIN2L()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert signed long encoded bytes into Harbour numeric
 *  $SYNTAX$
 *      BIN2L( <cBuffer> ) --> nNumber
 *  $ARGUMENTS$
 *      <cBuffer> is a character string that contain 32 bit encoded signed
 *      long integer (least significant byte first). The first four bytes
 *      are taken into account, the rest if any are ignored.
 *  $RETURNS$
 *      BIN2L() return numeric integer (or 0 if <cBuffer> is not a string).
 *  $DESCRIPTION$
 *      BIN2L() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. BIN2L() take four bytes of encoded
 *      32 bit signed long integer and convert it into standard Harbour
 *      numeric value.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      BIN2L() is the opposite of L2BIN()
 *  $EXAMPLES$
 *      // Show number of records in DBF
 *      FUNCTION main()
 *      LOCAL nHandle, cBuffer := space( 4 )
 *      nHandle := fopen( "test.dbf" )
 *      IF nHandle > 0
 *         fseek( nHandle, 4 )
 *         fread( nHandle, @cBuffer, 4 )
 *         ? "Number of records in file:", BIN2L( cBuffer )
 *         fclose( nHandle )
 *      ELSE
 *         ? "Can not open file"
 *      ENDIF
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(),FREAD()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      BIN2U()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert unsigned long encoded bytes into Harbour numeric
 *  $SYNTAX$
 *      BIN2U( <cBuffer> ) --> nNumber
 *  $ARGUMENTS$
 *      <cBuffer> is a character string that contain 32 bit encoded unsigned
 *      long integer (least significant byte first). The first four bytes
 *      are taken into account, the rest if any are ignored.
 *  $RETURNS$
 *      BIN2U() return numeric integer (or 0 if <cBuffer> is not a string).
 *  $DESCRIPTION$
 *      BIN2U() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. BIN2U() take four bytes of encoded
 *      32 bit unsigned long integer and convert it into standard Harbour
 *      numeric value.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      BIN2U() is the opposite of U2BIN()
 *  $EXAMPLES$
 *      // Show number of records in DBF
 *      FUNCTION main()
 *      LOCAL nHandle, cBuffer := space( 4 )
 *      nHandle := fopen( "test.dbf" )
 *      IF nHandle > 0
 *         fseek( nHandle, 4 )
 *         fread( nHandle, @cBuffer, 4 )
 *         ? "Number of records in file:", BIN2U( cBuffer )
 *         fclose( nHandle )
 *      ELSE
 *         ? "Can not open file"
 *      ENDIF
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      XPP
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(),FREAD()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      I2BIN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert Harbour numeric into signed short encoded bytes
 *  $SYNTAX$
 *      I2BIN( <nNumber> ) --> cBuffer
 *  $ARGUMENTS$
 *      <nNumber> is a numeric value to convert (decimal digits are ignored).
 *  $RETURNS$
 *      I2BIN() return two bytes character string that contain 16 bit
 *      encoded signed short integer (least significant byte first).
 *  $DESCRIPTION$
 *      I2BIN() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. I2BIN() take a numeric integer
 *      value and convert it into two bytes of encoded 16 bit signed short
 *      integer.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      I2BIN() is the opposite of BIN2I()
 *  $EXAMPLES$
 *      // Update DBF "last update" date
 *      #include "fileio.ch"
 *      FUNCTION main()
 *      LOCAL nHandle, cYear, cMonth, cDay
 *      use test
 *      ? "Original update date is:", lupdate()
 *      close
 *      nHandle := fopen( "test.dbf", FO_READWRITE )
 *      IF nHandle > 0
 *         fseek( nHandle, 1, )
 *         cYear  := I2BIN( 68 )
 *         cMonth := I2BIN(  8 )
 *         cDay   := I2BIN(  1 )
 *         fwrite( nHandle, cYear , 1 )   // write only the first byte
 *         fwrite( nHandle, cMonth, 1 )
 *         fwrite( nHandle, cDay  , 1 )
 *         fclose( nHandle )
 *         use test
 *         ? "New update date is:", lupdate()
 *         close
 *      ELSE
 *         ? "Can not open file"
 *      ENDIF
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2U(),BIN2W(),L2BIN(),W2BIN(),WORD(),U2BIN(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      W2BIN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert Harbour numeric into unsigned short encoded bytes
 *  $SYNTAX$
 *      W2BIN( <nNumber> ) --> cBuffer
 *  $ARGUMENTS$
 *      <nNumber> is a numeric value to convert (decimal digits are ignored).
 *  $RETURNS$
 *      W2BIN() return two bytes character string that contain 16 bit
 *      encoded unsigned short integer (least significant byte first).
 *  $DESCRIPTION$
 *      W2BIN() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. W2BIN() take a numeric integer
 *      value and convert it into two bytes of encoded 16 bit unsigned short
 *      integer.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      W2BIN() is the opposite of BIN2W()
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      XPP
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),WORD(),U2BIN(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      L2BIN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert Harbour numeric into signed long encoded bytes
 *  $SYNTAX$
 *      L2BIN( <nNumber> ) --> cBuffer
 *  $ARGUMENTS$
 *      <nNumber> is a numeric value to convert (decimal digits are ignored).
 *  $RETURNS$
 *      L2BIN() return four bytes character string that contain 32 bit
 *      encoded signed long integer (least significant byte first).
 *  $DESCRIPTION$
 *      L2BIN() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. L2BIN() take a numeric integer
 *      value and convert it into four bytes of encoded 32 bit signed long
 *      integer.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      L2BIN() is the opposite of BIN2L()
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2U(),BIN2W(),I2BIN(),W2BIN(),WORD(),U2BIN(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      U2BIN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Convert Harbour numeric into unsigned long encoded bytes
 *  $SYNTAX$
 *      U2BIN( <nNumber> ) --> cBuffer
 *  $ARGUMENTS$
 *      <nNumber> is a numeric value to convert (decimal digits are ignored).
 *  $RETURNS$
 *      U2BIN() return four bytes character string that contain 32 bit
 *      encoded unsigned long integer (least significant byte first).
 *  $DESCRIPTION$
 *      U2BIN() is one of the low level binary conversion functions, those
 *      functions convert between Harbour numeric and a character
 *      representation of numeric value. U2BIN() take a numeric integer
 *      value and convert it into four bytes of encoded 32 bit unsigned long
 *      integer.
 *
 *      You might ask what is the need for such functions, well, first of
 *      all it allow you to read/write information from/to a binary file
 *      (like extracting information from DBF header), it is also a useful
 *      way to share information from source other than Harbour (C for
 *      instance).
 *
 *      U2BIN() is the opposite of BIN2U()
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      XPP
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      WORD()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Converts double to integer values.
 *  $SYNTAX$
 *      WORD( <nDouble> ) --> <nInteger>
 *  $ARGUMENTS$
 *      <nDouble> is a numeric double value.
 *  $RETURNS$
 *      WORD() return an integer in the range +-32767
 *  $DESCRIPTION$
 *      This function converts double values to integers to use
 *      within the CALL command
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      The CA-Cl*pper NG states that WORD() will only work when used in CALL
 *      commands parameter list, otherwise it will return NIL, in Harbour
 *      it will work anywhere.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *       CALL
 *  $END$
 */