home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 436_01 / stringz.h < prev    next >
Encoding:
Text File  |  1994-10-07  |  10.0 KB  |  254 lines
  1. /*************************************************************************
  2.     STRINGZ.H -- Function prototypes for STRINGZ.OBJ.
  3.  
  4.     C-callable routines that offer augmented string handling
  5.     capabilities.  STRINGZ.OBJ is part of INCON.LIB, but also
  6.     may be linked separately if you don't need the input
  7.     management provided by INCON.  Rather than keep track of
  8.     several versions of STRINGZ.OBJ, the routines declared
  9.     here are all FAR; they may be linked to programs compiled
  10.     under any memory model with only a small penalty to
  11.     small-code programs, which must still make far calls.
  12.  
  13.     None of the routines in STRINGZ.OBJ allocate memory for
  14.     destination strings or check for overflow in copying to them.
  15.     The calling routine is responsible for insuring that enough
  16.     space is available for the destination strings, including
  17.     terminating null bytes.
  18.  
  19.     Only ReplStr and InsStr check whether the destination string
  20.     will wrap around at the end of a segment, since the total
  21.     length of the destination may grow dynamically.
  22.  
  23.     The buffers supplied to these routines in DestStr and
  24.     SrcStr may be identical; only InsStr and ReplStr, due to
  25.     the nature of their operations, refuse to continue in that
  26.     circumstance.  All of the routines, however, return a null
  27.     DestStr in certain circumstances, so it is generally better
  28.     if DestStr and SrcStr name two different string buffers.
  29.  
  30.     Assembler:    Borland TASM 1.01 (tasm /ml/t/w2/z stringz;)
  31.  
  32.     INCON source files and the object and library files created from
  33.     them are:
  34.         Copyright (c) 1993-94, Richard Zigler.
  35.     You may freely distribute unmodified source, object, and library
  36.     files, and incorporate them into your own non-commercial software,
  37.     provided that this paragraph and the program name and copyright
  38.     strings defined in INCON.C are included in all copies.
  39. *************************************************************************/
  40.  
  41.  
  42. /****
  43.     Function Prototypes
  44.  
  45.     The parameter and return types, and the routine distances,
  46.     are all declared "far", so that these routines can be linked
  47.     with programs under any memory model.
  48.  
  49.     These routines can handle strings up to 32767 bytes long.
  50. ****/
  51.  
  52. char far * far pascal LeftStr        ( char far *, char far *, short            );
  53. char far * far pascal MidStr        ( char far *, char far *, short, short    );
  54. char far * far pascal RightStr    ( char far *, char far *, short            );
  55. char far * far pascal lJust        ( char far *, char far *, short, short    );
  56. char far * far pascal cJust        ( char far *, char far *, short, short    );
  57. char far * far pascal rJust        ( char far *, char far *, short, short    );
  58. char far * far pascal lTrim        ( char far *, char far *                    );
  59. char far * far pascal rTrim        ( char far *, char far *                    );
  60. char far * far pascal ReplStr        ( char far *, char far *, short            );
  61. char far * far pascal InsStr        ( char far *, char far *, short            );
  62. char far * far pascal TemplStr    ( char far *, char far *, short            );
  63.  
  64. /*************************************************************************
  65.  
  66.     char far * far pascal LeftStr( DestStr, SrcStr, Num )
  67.  
  68.         char far * DestStr            Destination string
  69.         char far * SrcStr                Source string
  70.         short Num                        Number of characters to copy
  71.  
  72.     Copies Num characters from left end of SrcStr to DestStr    returns
  73.     pointer to DestStr.
  74.  
  75.     If Num is greater than or equal to the length of SrcStr, all of
  76.     SrcStr is copied.  If Num is outside the range 1 to 32767,
  77.     DestStr is returned null.
  78.  
  79.   **********************************************************************
  80.  
  81.     char far * far pascal MidStr( DestStr, SrcStr, Start, Num )
  82.  
  83.         char far * DestStr            Destination string
  84.         char far * SrcStr                Source string
  85.         short Start                        First character to copy
  86.         short Num                        Number of characters to copy
  87.  
  88.     Copies Num characters from SrcStr to DestStr beginning at Start
  89.     in SrcStr; returns pointer to DestStr.
  90.  
  91.     If Start is greater than the length of SrcStr, DestStr is
  92.     returned null.  If Num is greater than the remainder of SrcStr,
  93.     all characters from Start to the end of SrcStr are copied.  If
  94.     either Start or Num is outside the range 1 to 32767, DestStr
  95.     is returned null.
  96.  
  97.   **********************************************************************
  98.  
  99.     char far * far pascal RightStr( DestStr, SrcStr, Num )
  100.  
  101.         char far * DestStr            Destination string
  102.         char far * SrcStr                Source string
  103.         short Num                        Number of characters to copy
  104.  
  105.     Copies Num characters from right end of SrcStr to DestStr;
  106.     returns pointer to DestStr.
  107.  
  108.     If Num is greater than or equal to the length of SrcStr, all
  109.     of SrcStr is copied.  If Num is outside the range 1 to 32767,
  110.     DestStr is returned null.
  111.  
  112.   **********************************************************************
  113.  
  114.     char far * far pascal lJust( DestStr, SrcStr, Size, Chr )
  115.  
  116.         char far * DestStr            Destination string
  117.         char far * SrcStr                Source string
  118.         short Size                        Width of field
  119.         char Chr                            "Pad" character
  120.  
  121.     Copies SrcStr to DestStr, left justified in a field of Size
  122.     characters; returns pointer to DestStr.
  123.  
  124.     DestStr is padded on the right with Chr.  Chr may be any
  125.     character, including control codes.  Control codes behave as
  126.     they normally would, either printing a graphics character or
  127.     taking a specific action.  If the length of SrcStr is greater
  128.     than Size, SrcStr is truncated on the right.  If Size is outside
  129.     the range 1 to 32767, DestStr is returned null.  If SrcStr is
  130.     null, DestStr is filled with Size repetitions of Chr.
  131.  
  132.   **********************************************************************
  133.  
  134.     char far * far pascal cJust( DestStr, SrcStr, Size, Chr )
  135.  
  136.         char far * DestStr            Destination string
  137.         char far * SrcStr                Source string
  138.         short Size                        Width of field
  139.         char Chr                            "Pad" character
  140.  
  141.     Copies SrcStr to DestStr, centered in a field of Size
  142.     characters; returns pointer to DestStr.
  143.  
  144.     DestStr is padded on the left and right with Chr.  Chr may
  145.     be any character, with no provision for excluding ASCII control
  146.     codes.  If the total padding required to center SrcStr is odd,
  147.     the extra character is added on the right.  If the length of
  148.     SrcStr is greater than Size, SrcStr is truncated on the right.
  149.     If Size is outside the range 1 to 32767, DestStr is returned
  150.     null.  If SrcStr is null, DestStr is filled with Size
  151.     repetitions of Chr.
  152.  
  153.   **********************************************************************
  154.  
  155.     char far * far pascal rJust( DestStr, SrcStr, Size, Chr )
  156.  
  157.         char far * DestStr            Destination string
  158.         char far * SrcStr                Source string
  159.         short Size                        Width of field
  160.         char Chr                            "Pad" character
  161.  
  162.     Copies SrcStr to DestStr, right justified in a field of Size
  163.     characters; returns pointer to DestStr. 
  164.  
  165.     DestStr is padded on the left with Chr.  Chr may be any
  166.     character, including control codes.  Control codes behave as
  167.     they normally would, either printing a graphics character or
  168.     taking a specific action.  If the length of SrcStr is greater
  169.     than Size, SrcStr is truncated on the right.  If Size is outside
  170.     the range 1 to 32767, DestStr is returned null.  If SrcStr is
  171.     null, DestStr is filled with Size repetitions of Chr.
  172.  
  173.   **********************************************************************
  174.  
  175.     char far * far pascal lTrim( DestStr, SrcStr )
  176.  
  177.         char far * DestStr            Destination string
  178.         char far * SrcStr                Source string
  179.  
  180.     Copies SrcStr to DestStr with leading spaces and control
  181.     characters removed; returns pointer to DestStr.
  182.  
  183.   **********************************************************************
  184.  
  185.     char far * far pascal rTrim( DestStr, SrcStr )
  186.  
  187.         char far * DestStr            Destination string
  188.         char far * SrcStr                Source string
  189.  
  190.     Copies SrcStr to DestStr with trailing spaces and control
  191.     characters removed; returns pointer to DestStr.
  192.  
  193.   **********************************************************************
  194.  
  195.     char far * far pascal ReplStr( DestStr, SrcStr, Start )
  196.  
  197.         char far * DestStr            Destination string
  198.         char far * SrcStr                Source string
  199.         short Start                        Start position
  200.  
  201.     Replaces characters in DestStr with those from SrcStr; returns
  202.     pointer to DestStr.
  203.     
  204.     If Start is greater than the length of DestStr, ScrStr is
  205.     concatenated to DestStr.  If DestStr is null, SrcStr is copied
  206.     to DestStr.  If Start or the length of SrcStr is outside the range
  207.     1 to 32767, DestStr is returned null.  If the length of DestStr
  208.     will grow so that it crosses a segment boundary, DestStr is
  209.     returned null.
  210.  
  211.   **********************************************************************
  212.  
  213.     char far * far pascal InsStr( DestStr, SrcStr, Start )
  214.  
  215.         char far * DestStr            Destination string
  216.         char far * SrcStr                Source string
  217.         short Start                        Start position
  218.  
  219.     Inserts characters from SrcStr into DestStr; returns
  220.     pointer to DestStr.
  221.  
  222.     If Start is greater than the length of DestStr, ScrStr is
  223.     concatenated to DestStr.  If DestStr is null, SrcStr is copied
  224.     to DestStr.  If Start or the length of SrcStr is outside the range
  225.     1 to 32767, DestStr is returned null.  If the length of DestStr
  226.     will grow so that it crosses a segment boundary, DestStr is
  227.     returned null.
  228.  
  229.   **********************************************************************
  230.  
  231.     char far * far pascal TemplStr( DestStr, SrcStr, Chr )
  232.  
  233.         char far * DestStr            Destination string
  234.         char far * SrcStr                Source string
  235.         short Chr                        Flag character
  236.  
  237.     Copies characters from SrcStr into DestStr.  Returns pointer to
  238.     DestStr.
  239.  
  240.     At entry, DestStr points to a template to be filled in with
  241.     characters from SrcStr and Chr matches a marker in DestStr
  242.     that mark where those characters go.  Note that Chr must NOT
  243.     occur in DestStr except as a marker for characters from SrcStr.
  244.     For example, in the template "(999) 999-9999" Chr should be "9".
  245.     Since " ", "(", ")", and "-" are part of the template, they
  246.     would not be suitable as markers.  TemplStr moves characters
  247.     from SrcStr to DestStr in order, continuing until SrcStr is
  248.     exhausted or the end of DestStr is reached.  If SrcStr and
  249.     DestStr are identical, DestStr is returned unchanged.
  250.  
  251. *************************************************************************/
  252.  
  253. /**** EOF:  STRINGZ.H ****/
  254.