eX version 0.4b User's Manual                         File eXMan23.txt
(C) Copyright 1995, 1996 William E. Wilgus III.   All rights reserved.


String Functions
 

Conversion

These are `filter' functions and may take the form:

                     function eev$

Alphabetic Case


lcase
     Returns a copy of eev$ with any upper case alphabetic
     characters converted to lower case alphabetic characters.

ocase
     Returns a string with the case of each alphabetic character
     within eev reversed.

pcase
     Returns a string with the alphabetic case of eev$ consistent with
     the requirements of a proper noun.  It does not necessarily
     return a correctly capitalized title:

                pcase "the hound of the baskervilles"
     returns 
                    The Hound Of The Baskervilles

ucase
     Returns eev$ with any lower case ASCII alphabetic characters  
     converted to upper case ASCII alphabetic characters.  




Character Representation


bin
     See in the section `Hermaphrodite Functions'

ced  (Not available in eX Lite.)
     Returns the string whose byte-wise decimal representation is the 
     argument string.  The function, and hence its name, is the
     inverse of the function  dec.
             ced " 101 088"                 returns     "eX"
             short msblsb ced " 000 001"    returns      1

dec  
     Returns a string containing the decimal representation of each
     byte within eev$.  
             dec "eX"                       returns     " 101 088"
             dec msblsb short$ 1            returns     " 000 001"

nib
     Returns the string whose byte-wise binary representation is the  
     argument string.  The function, and hence its name, is the
     inverse of the function bin.  
          nib "0110010101011000"                returns   " eX" 
          short msblsb nib "0000000000000001"   returns   1 

xeh
     Returns the string whose byte-wise hexadecimal representation is
     the argument string.  The function, and hence its name, is the
     inverse of the function hex.  
              xeh "6558"                 returns    "eX"
              short msblsb xeh "0001"    returns    1




Creation


chr
                    chr eev<<, eev ... >>
     Returns a single string containing any string argument(s) and/or 
     characters produced by any numeric argument in the range 
     0--255.  With arguments that return both a string and a numeric,
     the string is concatenated first.  The parenthesized argument
     form is not allowed.  Some examples. 

         chr 65    
         chr 84, 104, 101, 32, $eX := "eX", " Computer Language.
         chr &b"110000", &b"110001", &h"FF", &o"10"

form
     See in the section `Terminal', `Output'. 

spaces  (Not available in eX Lite.)
                    spaces eev#
     Returns a string of eev# spaces (ASCII code 32). 

str
     See in the section `Data Type Cast Functions'. 

string
                    string(eev1, eev2#)
     Returns a string of eev2# characters, all of which are the first
     character in the string eev1$ or the character represented by
     eev1#.  If given as a numeric, eev1# must be an integer in the
     range 0--255.



Filters

Exclusion


except
                         except(eev1$, eev2)
     Returns a copy of eev1$ minus any and all occurances of eev2,
     which may be given as a string or an integer in the range 
     0--255.  If eev2 is given as the null string (""), eev1$ is 
     returned. 

exceptA  (Not available in eX Lite.)
                         exceptA eev$
     Returns eev$ minus any ASCII alphabetic characters.  

exceptC  (Not available in eX Lite.)
                         exceptC eev$
     Returns eev$ minus any ASCII Control Codes (0--31).  

exceptE  (Not available in eX Lite.)
                         exceptE eev$
     Returns eev$ minus any Extended ASCII codes (128--255).  

exceptL  (Not available in eX Lite.)
                         exceptL eev$
     Returns eev$ minus any ASCII lowercase alphabetic characters.  

exceptN  (Not available in eX Lite.)
                         exceptN eev$
     Returns eev$ minus any ASCII numeric characters.  
     (Any numeric punctuation commas and decimal points are also
     removed.)  
     ASCII codes 45 (-) and 43 (+) are considered to be numeric if
     they immediately precede or follow an ASCII digit.

exceptS  (Not available in eX Lite.)
                         exceptS eev$
     Returns eev$ minus any ASCII spaces (code 32).  

exceptU  (Not available in eX Lite.)
                         exceptU eev$
     Returns eev$ minus any ASCII uppercase alphabetic characters.  



Exclusive Inclusion

only  (Not available in eX Lite.)
                         only(eev1$, eev2)
     Returns a copy of eev1$ that includes only any and all occurances
     of eev2.  eev2 may be given as a string or an integer in the
     range 0--255.  If eev2 is given as a null "", the null string
     "" is returned. 

onlyA  (Not available in eX Lite.)
                         onlyA eev$
     Returns a string containing only the ASCII alphabetic characters
     from within eev$, if any.  It considers the ASCII space (code 32)
     to be alphabetic.  

onlyC  (Not available in eX Lite.)
                         onlyC eev$
     Returns a string containing only the ASCII control codes (0--31)
     from within eev$, if any.  

onlyE  (Not available in eX Lite.)
                         onlyE eev$
     Returns a string containing only the extended ASCII codes
     (128--255) from within eev$, if any.  

onlyL  (Not available in eX Lite.)
                         onlyL eev$
     Returns a string containing only the lower case ASCII alphabetic 
     characters from within eev, if any.  It considers the
     ASCII space (code 32) to be lower case alphabetic.  

onlyN  (Not available in eX Lite.)
                         onlyN eev$
     Returns a string containing only the ASCII numeric characters and
     their punctuating commas and decimal points from within eev$, if
     any.  ASCII codes 43 (+) and 45 (-) are considered to be 
     numeric if they immediately precede or follow an ASCII digit.  
     It considers the space (ASCII code 32) to be a numeric character
     if it immediately precedes or follows a numeric character.

onlyS  (Not available in eX Lite.)
                         onlyS eev$
     Returns a string containing only the ASCII space characters from
     within eev$, if any.

onlyU  (Not available in eX Lite.)
                         onlyU eev$
     Returns a string containing only the upper case ASCII alphabetic
     characters from within eev$, if any.  It considers the ASCII
     space (code 32) to be upper case alphabetic.



General

len
                         len eev$
     Returns the length of eev$.  I'm thinking of having it return
     eev$ also.

trim
                         trim eev$
     Returns eev$ after removing any leading and/or trailing spaces
     (ASCII code 32).  

trimL
                         trimL eev$
     Returns eev$ after removing any leading spaces (ASCII code 32).  

trimR
                         trimR eev$
     Returns eev$ after removing any trailing spaces (ASCII code 32). 



Sub-String

All of the sub-string functions are assignable with the exceptions of 
subst, swimL and swimR which are assignments in themselves, TermNo,
and the ancillary function MatchPos.  With the exception of asc, the
length of the assigned value need not match the length of the
assignment object sub-string and may even be null "".  Note that
sequential files are illegal as assignment objects. 

The assignable functions are a bit unusual in that if the object of
the function argument ObjectString$ (which is also the object of any
assignment) is given as a literal---or presented as a literal via an
aggregation---and an assignment is made, the value of the literal
reflecting the changes made through the assignment is returned.  The
literal is not changed.  However, if the function (and assignment)
object ObjectString$ is given as a data entity, the assigned value is
returned and the value within the data entity is altered.  The
purpose, of course, it to be able to obtain manipulated values without
changing the original. 

The following fully legal macro uses the sub-string function mid 
to illustrate:

     mid($x := "123456789", 1, 4) := "abcd"    returns   "abcd"
     mid($ ($x), 1, 4) := "0 "                 returns   "0 56789"

The terminal value of $x is "abcd56789". 



asc
     ASCII code function. 

                asc<<$> eev$ <<:= eev>>
                asc<<$>>(eev$) <<:= eev>>
                asc<<$>>(eev$, position#) <<:= eev>>

     Returns the ASCII Code of the byte that lies at the specified
     position (from the left side) within eev$.  If no character
     position is specified, the byte position is assumed to be 1.
     If the character position is beyond the right end of the data,
     the value -1 is returned.  The optional string suffix causes
     the an ASCII representation string to be returned. 

     If the asignment operator is provided with a string value, the
     string value is used for the assignment.  In this case, the
     returned value is the assignment value if a data entity is the
     assignment object, or the post-assignment value if the assign-
     ment object is not, or is made to appear to not be, a data
     entity.  The length of the string value need not be 1 character;
     if its length is greater, the string is expanded to fit it in.
     If the value assigned is the null string (""), the character at
     the assignment position is removed and the assignment string
     collapsed to fill the void.

     If the no string is provided for assignment, but a numeric is,
     the character at the position specified is replaced by a 
     character with the value of the numeric provided, which must be
     an integer in the range 0--255.  Here, the values returned by the
     function is the numeric values assigned.

anTerm  (Not available in eX Lite.)
          anTerm(ObjectString$, anTermNumber#) <<:= eev$>>

     Returns the exclusively ASCII alphabetic numeric term in 
     ObjectString$ specified by anTermNumber# if it exists and upon
     which assignment is conditional.  See also MatchPos, aTerm,
     nTerm, and Term in this section. 

aTerm  (Not available in eX Lite.)
          aTerm(ObjectString$, aTermNumber#) <<:= eev$>> 
     Returns the alphabetic term in ObjectString$ specified by 
     aTermNumber# if it exists and upon which assignment is
     conditional.  See also MatchPos, anTerm, nTerm, and Term in 
     this section. 

has  (Not available in eX Lite.)
     has(ObjectStr$, SearchStr$<<, start#>>, stop#>> >>) <<:= eev$>>

     Returns the first position of SearchStr$ within ObjectStr$, if
     any.  If SearchStr$ does not exist within ObjectStr$, 0 is
     returned and assignment is precluded.  The optional start#
     indicates at what position in ObjectStr$ the search is to begin
     and if not given is taken to be 1.  stop# may be given only if
     start# has been given and indicates the last position at which
     the search is allowed.  See also match, mid, opos, and subst.

LastPos
          LastPos(ObjectString$, SearchString$) <<:= eev$>>
     Returns the last position of SearchString$ within
     ObjectString$, if any.  If it does not exist within
     ObjectString$, 0 is returned and assignment is precluded.   See
     also match, mid, opos, and subst.

left
               left(Object$, length#) <<:= eev$>>
               left(Object$, SearchString$) <<:= eev$>>

     The first argument option returns length# characters from the
     left side of ObjectString$.  If less than length# characters are
     in ObjectString$, ObjectString$ is returned.  Note that eX will 
     crash if fewer than length# characters are in ObjectString$ and 
     an assignment is attempted.

     The second argument form returns the characters in
     ObjectString$ from the beginning of ObjectString$ up to, but not
     including, SearcgString$.  If SearchString$ does not exist within
     ObjectString$, ObjectString$ is returned. 

     See also mid and right. 

match  (Not available in eX Lite.)
          match(ObjectStr$, BeginningPattern$, 
                  EndingPattern<<, start#<<, stop#>> >>) << := eev$>>

     Pattern search function.  Returns a string matching the specified
     pattern and its position within ObjectString$, if any.  If no
     match is found, nulls (0 and "") are returned.  The position
     result of the search is also retrievable through the eX function
     MatchPos.  The optional start# indicates at what position in 
     ObjectString$ the search is to begin and if not given is taken to
     be 1.  The optional stop# specifies where the pattern matching
     search is to terminate, and if stop# is given, start# must be
     given.  A BeginningPattern$ of null ("") is considered to be a 
     `wild card' that is equal to the character in ObjectString$ at 
     the start# position.  An EndingPattern$ of null ("") is
     considered to be a `wild card' that is equal to the last
     character in ObjectString$, or if stop# is given, the character
     at that position.  If ObjectString$ is null (""), no match can be
     found.  Assignment is contingent upon a `match' being found. 

     The matching process is strictly left to right. 

         match("c:\subdir1\subdir2\filename.ext", "\"' ".")

     returns "c:\subdir1\subdir2\filename."  This function will
     probably be re-named `matchL' and an a function `matchR' that
     would return "\filename." added.  But then there also needs to be
     the functions FilePath, FileDriv, FileSpec, FileName, and
     FileExt.

     See also has, MatchPos, opos, and subst.

MatchPos  (Not available in eX Lite.)
     Returns the position of the `match' within the object string
     string found by the sub-string pattern-matching function match
     A value of 0 indicates no match was found.  MatchPos is also
     identically set by the sub-string functions anTerm, aTerm, 
     nTerm and Term.  See also match. 

mid
          mid(ObjectString$, position#, length#) <<:= eev$>>

     Returns the portion of ObjectString$ that begins at position# and
     is length# characters long.  length# may be 0 (primarily to
     provide the ability to `insert' a sub-string.  If 

                      position# + (length# - 1)

     is past the end of ObjectString$, returns only those characters
     that are in ObjectString$ beginning at position#.  See also has,
     left, match, opos, right, subst and any that I have forgotten. 

nTerm  (Not available in eX Lite.)
               nTerm(ObjectString$, nTermNumber#) <<:= eev$>>

     Returns the numeric term in ObjectString$ specified by 
     nTermNumber# if it exists and upon which assignment is
     conditional.  See also MatchPos, aTerm, anTerm, and Term in 
     this section. 

OPos  (Not available in eX Lite.)
          OPos(ObjectString$, SearchObject, n#) <<:= eev$>>

     Returns the position, if it exists, of the n#th occurance of 
     SearchObject in ObjectString$, and assignment is conditional upon
     its existence.  A numeric SearchObject represents a one-character
     string and must be an integer in the range 0--255.  

               OPos("101010", "10", 3)     returns    5
               OPos("101010", 49, 3)       returns    5
               OPos("101010", "2", 1)      returns    0
               OPos("101010", "1", 4)      returns    0


right
             right(ObjectString$, length#) <<:= eev$>>
             right(ObjectString$, SearchString$) <<:= eev$>>

     The first argument option returns the right length# characters 
     from eev$.  In the event that fewer than length# characters are
     within ObjectString$, ObjectString$ is returned.  

     The second argument option returns the characters in
     ObjectString$ subsequent to the first occurance of
     SearchString$ within ObjectString$, if any; otherwise, the null
     string "" is returned.  

         right("filename.ext", ".")     returns     "ext"

     See also left and mid.

subst  (Not available in eX Lite.)
          subst(ObjectString$, SearchString$,
                   SubstituteString<<, start#<<, stop#>> >>)

     Sub-string substitution function.  Replaces the first occurance
     of SearchString$ after the position start# (if given) in 
     ObjectString$ with SubstituteString$, as long as it is not before
     the position start# or after the position stop#.  If start# is
     not given, it is assumed to be 1.  If stop# is not given, stop#
     is taken as equal to the last position in ObjectString$.  If 
     stop# is given, start# must be given.  Returns true (-1) if the
     replacement occured, false (0) if it did not.  In either case, it
     returns ObjectString$ as it exists after any substitution and is
     an assignment in itself.  See also has, match and opos.

swimL
          swimL(ObjectString$, SearchString$, SwimPositions#)
          swimL(ObjectString$, position#, length#, SwimPositions#) 

     Moves a sub-string left SwimPositions# within ObjectString$ and
     gets its name from the similarity of its action to that of a
     swimmer moving through the water.  If fewer than SwimPositions#
     characters exist to the left of the sub-string `swimmer', padding
     is added (ASCII code 32 spaces) between the `swimmer' and the
     original beginning of ObjectString$ to make up the difference. 
     The `swimmer' may be specified as either a sub-string, in which
     case it is searched for and its first occurance, if any, `swims';
     or it may be specified as a character position and length within
     ObjectString$.  In either case, the `swimmer' must exist within
     ObjectString$ in order for any `swimming' to be done.  See also
     swimR in this section.

          swimL($x := "ABC", 2, 1, 4)    returns    "B  AC"
          swimL($x := "ABC", "x", 4)     returns    "ABC"

swimR
          swimR(ObjectString$, SubString$, SwimPositions#)
          swimL(ObjectString$, position#, length#, SwimPositions#)

     Moves a sub-string right SwimPositions# within ObjectString$ and
     gets its name from the similarity of its action to that of a
     swimmer moving through the water.  If fewer than SwimPositions#
     characters exist to the right of the sub-string `swimmer',
     padding is added (ASCII code 32 spaces) between the `swimmer' and
     the original end of ObjectString$ to make up the difference. 

     The `swimmer' may be specified as either a sub-string, in which
     case it is searched for and its first occurance, if any, `swims';
     or it may be specified as a character position and length within
     ObjectString$.  In either case, the `swimmer' must exist within
     ObjectString$ in order for any `swimming' to be done.  See also
     swimL.

          swimR($x := "ABC", 1, 1, 1)     returns    "ACB"

term
               term(ObjectString$, TermNumber#) <<:= eev$>>

     Returns the term within ObjectString$ specified by TermNumber# if
     it exists and upon which assignment is conditional.  See also
     MatchPos, aTerm, anTerm, and nTerm in this section. 

TermNo  (Not available in eX Lite.)
                    TermNo(String$, SearchString$)

     Returns the number of the term SearchString$ within String$, 
     if it exists.  See also has in this section. 



Tests

With the exception of is and occurs, they're all `filter' functions. 



Inclusion

anTerms  (Not available in eX Lite.)
                         anTerms String$

     Returns the number of terms within String$ that contain both 
     alphabetic and ASCII numeric characters but no others.  See also
     aTerms, nTerms, and terms in this section. 

aTerms  (Not available in eX Lite.)
                         aTerms String$

     Returns the number of purely alphabetic terms within String$. 
     See also anTerms, nTerms, and terms in this section. 

has  
     See in the `Sub-String' section. 

hasA  (Not available in eX Lite.)
                         hasA String$

     Returns the position of the first ASCII alphabetic character  
     in String$, if any.  Otherwise, 0 is returned.  

hasC  (Not available in eX Lite.)
                         hasC String$

     Returns the position of the first ASCII control code (0--31)
     within String$, if any.  Otherwise, 0 is returned.  

hasE  (Not available in eX Lite.)
                         hasE String$

     Returns the position of the first extended ASCII code (128--255)
     within String$, if any.  Otherwise, 0 is returned.  

hasL  (Not available in eX Lite.)
                         hasL String$

     Returns the position of the first ASCII lower case alphabetic
     character within String$, if any.  Otherwise, 0 is returned.  

hasN  (Not available in eX Lite.)
                         hasN String$

     Returns the position of the first ASCII numeric character
     within String$, if any.  Otherwise, 0 is returned.  The ASCII
     codes 43 (+) and 45 (-) are considered to be numeric if they are
     followed by an ASCII digit.  

hasS  (Not available in eX Lite.)
                         String$

     Returns the position of the first ASCII space (code 32) within
     String$, if any.  Otherwise, 0 is returned.  

hasU  (Not available in eX Lite.)
                         hasU String$

     Returns the position of the first upper case ASCII alphabetic  
     character within String$, if any.  Otherwise, 0 is returned.  

nTerms  (Not available in eX Lite.)
                         nTerms String$

     Returns the number of ASCII numeric terms (which may include
     formatting within String$.  See also aTerms, anTerms, and terms
     in this section. 

occurs  (Not available in eX Lite.)
                    occurs(String$, SearchObject)

     Returns the number of occurances of SearchObject within
     String$, if any.  A numeric SearchObject represents a
     one-character string and must be an integer in the range 0--255. 

          occurs("101010", "10")      returns    3
          occurs("101010", "2")       returns    0
          occurs("101010", 48)        returns    3

terms  (Not available in eX Lite.)
                         terms String$

     Returns the number of terms within String$.  See also aTerms,
     anTerms, and nTerms in this section. 



Exclusive Inclusion


is  (Not available in eX Lite.)
                    is(String$, TestValue)

     Returns true (-1) if String$ is comprised only of one or more
     copies of TestValue, otherwise it returns false (0).  Note that
     if given as a numeric, TestValue must be in the range 0--255.  

isA  (Not available in eX Lite.)
                         isA String$

     Returns true (-1) if String$ contains only ASCII alphabetic
     characters, otherwise false (0) is returned.  The space (ASCII
     code 32) is considered to be alphabetic.  

isC  (Not available in eX Lite.)
                         isC String$

     Returns true (-1) if String$ contains only ASCII control codes
     (0--31), otherwise false (0) is returned.  

isE  (Not available in eX Lite.)
                         isE String$

     Returns true (-1) if String$ contains only extended ASCII codes
     (128--255), otherwise false (0) is returned.  

isL  (Not available in eX Lite.)
                         isL String$

     Returns true (-1) if String$ contains only lower case ASCII
     alphabetic characters, otherwise false (0) is returned.  The
     space (ASCII code 32) is considered to be lower case alphabetic. 

isN  (Not available in eX Lite.)
                         isN String$

     Returns true (-1) if String$ contains only ASCII numeric
     characters, otherwise false (0) is returned.  Numeric punctuation
     commas and decimal points are considered to be numeric.  The
     ASCII codes 43 (+) and 45 (-) are considered to be numeric if
     they immediately precede or follow a numeric character.  ASCII
     spaces are considered to be numeric if they precede or follow a  
     numeric character.  

isS  (Not available in eX Lite.)
                         isS String$

     Returns true (-1) if String$ contains only ASCII spaces (code
     32), otherwise false (0) is returned.  

isU  (Not available in eX Lite.)
                         isU String$

     Returns true (-1) if String$ contains only upper case ASCII
     alphabetic characters, otherwise false (0) is returned.  The
     space (ASCII code 32) is considered to be upper case alphabetic. 


