!bestlib.doc

supplementary source file 1 for The BESTLibrary

================================================================================
=------------                THE BEST LIBRARY 2.32                 ------------=
=------------   THE FASTEST AND MOST EFFICIENT LIBRARY AVAILABLE   ------------=
=------------------------------------------------------------------------------=
=----------------------  292 PURE ASSEMBLER FUNCTIONS   -----------------------=
=----------------------       68 C CODED ROUTINES       -----------------------=
=----------------------                                 -----------------------=
=----------------------      TOTAL: 360 FUNCTIONS       -----------------------=
================================================================================

                    DOCUMENT LAST UPDATED  94/09/11   Sunday, September 11, 1994
                INDEPENDENTLY AUTHORED BY  GEORGE VANOUS                23:31.39


If you find this library useful, please let me know.  I like hearing that my
efforts are appreciated.

You can contact me via email: [e-mail]
or call me at [phone] or write to me:  George Vanous
                                             8930 Watson Court
                                             Delta, BC
                                             V4C 4T6

NOTE  This library will no longer be updated, since C is quickly being
      replaced by C++.  The BESTLibrary++ 1.0 will soon be released, an
      object version of The BESTLibrary 2.32.  As of today, it contains full
      support for 2D AND 3D rotation/scaling, timing classes, and text mode
      windowing classes, to mention a few.  Let me know if you are interested
      in obtaining the demo .EXE of what it can currently do.


This library covers the following categories:

      FILE           8 functions             TEXT          33 functions
        INI FILE     9 functions               ANIMATION    0 functions
      KEYBOARD      42 functions               ATTRIBUTE    8 functions
      LINKED LIST    4 functions               CHARACTER   16 functions
      MATH          13 functions               CURSOR      23 functions
        MATRIX      18 functions               GET          5 functions
        2D VECTORS  17 functions               STRING       8 functions
        3D VECTORS  17 functions               WINDOW       4 functions
      MISCELLANEOUS  9 functions             VGA                3 functions
      MOUSE         13 functions             VGA16             17 functions
      STRING        73 functions               ANIMATION        4 functions
        CHARACTER   15 functions               IMAGE            1 function
        CONVERSION   4 functions               COMPRESS IMAGE  10 functions
                                               PIXEL IMAGE      7 functions
                                               PLANE IMAGE      8 functions
                                             VGA256             2 functions

                         TOTAL:  360 ROUTINES

--------------------------------------------------------------------------------

B - changes in other functions have made this function unusable (temporary)
X - still under development

  ----------------------------------------------------------------------------
------------------------------------ FILE --------------------------------------

fil_count...........display the number of executions and some message
fil_count_reg.......same as "counter" except this is used for registered copies
fil_len.............return the length of a file, in bytes
fil_next_str........return the next string from a file
fil_next_word.......return the next word from a file
fil_read_to.........return the contents of a file upto and including a string
fil_read_to_strip...return the contents of a file upto and including a string
fil_skip_past.......skip past a string in a file
fil_skip_to.........skip to a string in a file

- - - - - - - - - - - - - - - - -  INI FILE  - - - - - - - - - - - - - - - - - -
ini_get_boolean.....read in a boolean parameter
ini_get_color.......read in a color
ini_get_number......read in a number
ini_get_position....read in and translate a screen position into a row number
ini_get_rows........read in the number of rows per screen
ini_get_state.......read in the keyboard state
ini_get_text........read in a text string
ini_get_yesno.......read in a YES or NO response
ini_read_section....read in the releveant text of a section

  ----------------------------------------------------------------------------
---------------------------------  KEYBOARD  -----------------------------------

kbd_all_off.............disable all of the three LOCKS and turns off light
kbd_all_on..............enable  all of the three LOCKS and turns on  light
kbd_caps_off............disable the CAPS LOCK key and turns off the light
kbd_caps_on.............enable  the CAPS LOCK key and turns on  the light
kbd_clear...............clear the keyboard buffer of all keystrokes
kbd_give................give control back to the original keyboard interrupt
kbd_hit.................check keyboard buffer to see if a key has been pressed
kbd_insert_off..........disable the INSERT mode
kbd_insert_on...........enable  the INSERT mode
kbd_is_all_on...........report if all three LOCKS are active
kbd_is_alt..............report if either alt is depressed
kbd_is_alt_left.........report if the left alt is depressed
kbd_is_alt_left_only....report if only the left alt is depressed
kbd_is_alt_right........report if the right alt is depressed
kbd_is_alt_right_only...report if only the right alt is depressed
kbd_is_alt_only.........report if only an alt is depressed (not ctrl or shift)
kbd_is_caps_on..........report if CAPS LOCK is active
kbd_is_ctrl.............report if either ctrl is depressed
kbd_is_ctrl_left........report if the left ctrl is depressed
kbd_is_ctrl_left_only...report if only the left ctrl is depressed
kbd_is_ctrl_right.......report if the left ctrl is depressed
kbd_is_ctrl_right_only..report if only the right ctrl is depressed
kbd_is_ctrl_only........report if only ctrl is depressed (and not alt or shift)
kbd_is_insert_on........report if INSERT is active
kbd_is_num_on.. ........report if NUM LOCK is active
kbd_is_scroll_on........report if SCROLL LOCK is active
kbd_is_shift............report if either shift is depressed
kbd_is_shift_left.......report if the left shift is depressed
kbd_is_shift_left_only..report if only the left shift is depressed
kbd_is_shift_right......report if the right shift is depressed
kbd_is_shift_right_only.report if only the right shift is depressed
kbd_is_shift_only.......report if only shift is depressed (and not alt or ctrl)
kbd_num_off.............disable the NUM LOCK key and turns off the light
kbd_num_on..............enable  the NUM LOCK key and turns on  the light
kbd_rate................set typematic rate and delay for repeat-key action
kbd_scroll_off..........disable the SCROLL LOCK key and turns off the light
kbd_scroll_on...........enable  the SCROLL LOCK key and turns on  the light
kbd_status_load.........restore the previously saved keyboard status
kbd_status_save.........save the keyboard status of insert, caps/num/scroll lock
kbd_take................take control of the keyboard interrupt
getchr..................get a character from the keyboard buffer
getchre.................same as getchr, but also echoes character to the screen

  ----------------------------------------------------------------------------
--------------------------------  LINKED LIST  ---------------------------------

lst_find............search for a node of a linked list
lst_free_double.....deallocate each node of a doubly linked list
lst_free_single.....deallocate each node of a singly linked list
lst_tail............return the tail of a linked list
lst_unlink_double...unlink a node from a doubly linked list
lst_unlink_single...unlink a node from a singly linked list

  ----------------------------------------------------------------------------
-----------------------------------  MATH  -------------------------------------

max_byte............return the maximum of a list of byte
max_int.............return the maximum of a list of integers
max_shortint........return the maximum of a list of short integers
max_word............return the maximum of a list of words
min_byte............return the minimum of a list of bytes
min_int.............return the minimum of a list of integers
min_shortint........return the minimum of a list of short integers
min_word............return the minimum of a list of words

- - - - - - - - - - - - - - - - - - MATRIX - - - - - - - - - - - - - - - - - - -
m3_add..............add two 3x3 matrices
m3_copy.............return a copy of a 3x3 matrix
m3_det............X.return the determinant of a 3x3 matrix
m3_div............X.divide two 3x3 matrices
m3_inv............X.return the inverse of a 3x3 matrix
m3_mul..............multiply two 3x3 matrices
m3_new..............create and initialize a new 3x3 matrix
m3_sub..............subtract two 3x3 matrices
m3_transpose........transpose a 3x3 matrix
m4_add..............add two 4x4 matrices
m4_copy.............return a copy of a 4x4 matrix
m4_det............X.return the determinant of a 4x4 matrix
m4_div............X.divide two 4x4 matrices
m4_inv............X.return the inverse of a 4x4 matrix
m4_mul..............multiply two 4x4 matrices
m4_new..............create and initialize a new 4x4 matrix
m4_sub..............subtract two 4x4 matrices
m4_transpose........transpose a 4x4 matrix

- - - - - - - - - - - - - - - - - 2D VECTORS - - - - - - - - - - - - - - - - - -
v2_add..............add two 2D vector
v2_combine..........return the linear combination of two 2D vectors
v2_copy.............return a copy of a 2D vector
v2_dot..............return the dot product of two 2D vectors
v2_len..............return the magnitude (length) of 2D vector
v2_len_sqr..........return the magnitude (length) of 2D vector squared
v2_lerp.............linearly interpolate between two 2D vectors by some amount
v2_mul..............multiply two 2D vectors component-wise
v2_mul_by_matrix..X.multiply a 2D point by a matrix
v2_mul_by_proj......multiply a 2D point by a projection matrix
v2_neg..............negate a 2D vector
v2_new..............create and initialize a new 2D vector
v2_norm.............normalize a 2D vector (becomes unit length)
v2_ortho............return some orthogonal 2D vector to a 2D vector
v2_scale............scale a 2D vector to some new length
v2_seg_len..........return distance (line segment length) between two 2D points
v2_sub..............subtract two 2D vectors

- - - - - - - - - - - - - - - - - 3D VECTORS - - - - - - - - - - - - - - - - - -
v3_add..............add two 3D vector
v3_combine..........return the linear combination of two 3D vectors
v3_copy.............return a copy of a 3D vector
v3_cross............return the cross product of two 3D vectors
v3_dot..............return the dot product of two 3D vectors
v3_len..............return the magnitude (length) of 3D vector
v3_len_sqr..........return the magnitude (length) of 3D vector squared
v3_lerp.............linearly interpolate between two 3D vectors by some amount
v3_mul..............multiply two 3D vectors component-wise
v3_mul_by_matrix....multiply a 3D point by a matrix
v3_mul_by_proj......multiply a 3D point by a projection matrix
v3_neg..............negate a 3D vector
v3_new..............create and initialize a new 3D vector
v3_norm.............normalize a 3D vector (becomes unit length)
v3_ortho..........X.return some orthogonal 3D vector to a 3D vector
v3_scale............scale a 3D vector to some new length
v3_seg_len..........return distance (line segment length) between two 3D points
v3_sub..............subtract two 3D vectors

  ----------------------------------------------------------------------------
-------------------------------  MISCELLANEOUS	--------------------------------

beep................beeps the speaker
bestlib_init........initialize THE BEST LIBRARY and set default values
boot................either warm of cold boot the system
dos_shell...........shells to DOS, returning upon the user typing "EXIT"
msec................delays the computer for a specific number of milliseconds
sound_off...........stops any sound coming from the speaker
stopw...............set a delay stopwatch to a specific clock-tick delay
video_get...........read the current video mode
video_set...........change the video mode

  ----------------------------------------------------------------------------
-----------------------------------  MOUSE  ------------------------------------

ms_get..............store the location of the mouse cursor
ms_getx.............return the mouse cursor abscissa
ms_gety.............return the mouse cursor ordinate
ms_hide.............hides the mouse cursor
ms_init.............initialize the mouse and set "mousedata" values to default
ms_kill.............completely disable the mouse driver
ms_range............set the mouse cursor's minimum and maximum range of movement
ms_set..............set the mouse cursor's abscissa and ordinate
ms_setx.............set the mouse cursor's abscissa
ms_sety.............set the mouse cursor's ordinate
ms_shape............change the mouse character in text mode
ms_show.............display the mouse cursor
ms_stat.............store detailed information about the mouse's status

  ----------------------------------------------------------------------------
----------------------------------  STRING  ------------------------------------

case_down...........return an UPPERCASE letter as lowercase
case_down_ptr.......convert an UPPERCASE letter to lowercase
case_flip...........return the opposite case of a letter
case_flip_ptr.......convert a letter to the opposite case
case_up.............return a lowercase letter as UPPERCASE
case_up_ptr.........convert a lowercase letter to UPPERCASE
is_number_dec.......check if a string is a decimal number
is_number_hex.......check if a string is a hexadecimal number
mem_copy............makes a copy of a memory location
scan_byte...........search for a one-byte value
scan_byte_not.......search for any other one-byte value
scan_bytes..........search for one of several one-byte values
scan_bytes_not......search for any other one-byte values
scan_str............search for a string of characters