path: root/src/TCollection/TCollection_AsciiString.cdl

-- File:        TCollection_AsciiString.cdl
-- Created:     Mon Feb 22 16:57:04 1993
-- Author:      Mireille MERCIEN
--              <mip@sdsun4>
---Copyright:    Matra Datavision 1993


class AsciiString from TCollection
    	---Purpose: A variable-length sequence of ASCII characters
    	-- (normal 8-bit character type). It provides editing
    	-- operations with built-in memory management to
    	-- make AsciiString objects easier to use than
    	-- ordinary character arrays.
    	-- AsciiString objects follow value semantics; in
    	-- other words, they are the actual strings, not
    	-- handles to strings, and are copied through
    	-- assignment. You may use HAsciiString objects
    	-- to get handles to strings.

uses   ExtendedString from TCollection

raises 
    NullObject, 
    OutOfRange, 
    NumericError, 
    NegativeValue

is
    Create returns AsciiString from TCollection;
    ---Purpose: Initializes a AsciiString to an empty AsciiString.

    Create ( message : CString ) returns AsciiString from TCollection
    ---Purpose: Initializes a AsciiString with a CString.
    raises NullObject;

    Create ( message : CString ; aLen : Integer )
         returns AsciiString from TCollection
    ---Purpose: Initializes a AsciiString with a CString.
    raises NullObject;

    Create ( aChar : Character) returns AsciiString from TCollection;
    ---Purpose: Initializes a AsciiString with a single character.

    Create ( length : Integer; filler : Character)
              returns AsciiString from TCollection;
    ---Purpose: Initializes an AsciiString with <length> space allocated.
    -- and filled with <filler>. This is usefull for buffers.

    Create ( value : Integer ) returns AsciiString from TCollection
    ---Purpose: Initializes an AsciiString with an integer value
    raises NullObject;

    Create ( value : Real ) returns AsciiString from TCollection
    ---Purpose: Initializes an AsciiString with a real value
    raises NullObject;

    Create ( astring : AsciiString from TCollection ) 
            returns AsciiString from TCollection;
    ---Purpose: Initializes a AsciiString with another AsciiString.

    Create ( astring : AsciiString from TCollection ; message : Character ) 
            returns AsciiString from TCollection;
    ---Purpose: Initializes a AsciiString with copy of another AsciiString
    --          concatenated with the message character.

    Create ( astring : AsciiString from TCollection ; message : CString ) 
            returns AsciiString from TCollection;
    ---Purpose: Initializes a AsciiString with copy of another AsciiString
    --          concatenated with the message string.

    Create ( astring : AsciiString from TCollection ; message : AsciiString ) 
            returns AsciiString from TCollection;
    ---Purpose: Initializes a AsciiString with copy of another AsciiString
    --          concatenated with the message string.

    Create(astring : ExtendedString from TCollection; 
           replaceNonAscii: Character from Standard = 0)
    ---Purpose: Creation by converting an extended string to an ascii string.
    --          If replaceNonAscii is non-null charecter, it will be used 
    --          in place of any non-ascii character found in the source string.
    --          Otherwise, raises OutOfRange exception if at least one character
    --          in the source string is not in the "Ascii range".
    returns AsciiString from TCollection
    raises OutOfRange from Standard;
          
   AssignCat (me : out ; other : Character )
   ---Level: Public
   ---Purpose: Appends <other>  to me. This is an unary operator.
   ---C++: alias operator +=
   raises NullObject from Standard
   is static;

   AssignCat (me : out ; other : Integer from Standard )
   ---Level: Public
   ---Purpose: Appends <other>  to me. This is an unary operator.
   ---C++: alias operator +=
   raises NullObject from Standard
   is static;

   AssignCat (me : out ; other : Real from Standard )
   ---Level: Public
   ---Purpose: Appends <other>  to me. This is an unary operator.
   ---C++: alias operator +=
   raises NullObject from Standard
   is static;

   AssignCat (me : out ; other : CString)
   ---Level: Public
   ---Purpose: Appends <other>  to me. This is an unary operator.
   -- ex: aString += "Dummy"
   -- To catenate more than one CString, you must put a 
   -- AsciiString before.
   --  Example: aString += "Hello " + "Dolly"  IS NOT VALID !
   -- But astring += anotherString + "Hello " + "Dolly" is valid.
   ---C++: alias operator +=
   raises NullObject from Standard
   is static;

   AssignCat (me : out ; other : AsciiString from TCollection)
   ---Level: Public
   ---Purpose: Appends <other> to me. This is an unary operator.
   --  Example: aString += anotherString
   ---C++: alias operator +=
    is static;

   Capitalize(me : out)
   ---Level: Public
   ---Purpose: Converts the first character into its corresponding 
   -- upper-case character and the other characters into lowercase
   --  Example: before
   --   me = "hellO "
   -- after
   --   me = "Hello "
    is static;

--   Cat(me; other : CString from Standard; result : out AsciiString from TCollection )
--      is private;

   Cat (me ; other : Character from Standard) returns AsciiString from TCollection
   ---Level: Public
   ---Purpose: Appends <other>  to me.
   -- Syntax:
   -- aString = aString + "Dummy"   
   --  Example: aString contains "I say "
   -- aString = aString + "Hello " + "Dolly"
   -- gives "I say Hello Dolly"
   -- To catenate more than one CString, you must put a String before.
   -- So the following example is WRONG !
   --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
   -- This rule is applicable to AssignCat (operator +=) too.
   ---C++: alias operator +
   ---C++: inline
   raises NullObject from Standard
   is static;

   Cat (me ; other : Integer from Standard) returns AsciiString from TCollection
   ---Level: Public
   ---Purpose: Appends <other>  to me.
   -- Syntax:
   -- aString = aString + 15;  
   --  Example: aString contains "I say "
   -- gives "I say 15"
   -- To catenate more than one CString, you must put a String before.
   -- So the following example is WRONG !
   --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
   -- This rule is applicable to AssignCat (operator +=) too.
   ---C++: alias operator +
   ---C++: inline
   raises NullObject from Standard
   is static;

   Cat (me ; other : Real from Standard) returns AsciiString from TCollection
   ---Level: Public
   ---Purpose: Appends <other>  to me.
   -- Syntax:
   -- aString = aString + 15.15;
   --  Example: aString contains "I say "
   -- gives "I say 15.15"
   -- To catenate more than one CString, you must put a String before.
   -- So the following example is WRONG !
   --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
   -- This rule is applicable to AssignCat (operator +=) too.
   ---C++: alias operator +
   ---C++: inline
   raises NullObject from Standard
   is static;

    Cat (me ; other : CString from Standard)
           returns AsciiString from TCollection
    ---Level: Public
    ---Purpose: Appends <other>  to me.
    -- Syntax:
    -- aString = aString + "Dummy"   
    --  Example: aString contains "I say "
    -- aString = aString + "Hello " + "Dolly"
    -- gives "I say Hello Dolly"
    -- To catenate more than one CString, you must put a String before.
    -- So the following example is WRONG !
    --      aString = "Hello " + "Dolly"  THIS IS NOT ALLOWED
    -- This rule is applicable to AssignCat (operator +=) too.
    ---C++: alias operator +
    ---C++: inline
    is static;

--   Cat(me; other : AsciiString from TCollection;
--           result : out AsciiString from TCollection )
--      is private;
      
   Cat (me ; other : AsciiString from TCollection) 
   returns AsciiString from TCollection
   ---Level: Public
   ---Purpose: Appends <other> to me.
   --  Example: aString = aString + anotherString
   ---C++: alias operator +
   ---C++: inline
   is static;

   Center(me : out; 
          Width : Integer from Standard;
          Filler : Character from Standard) 
   raises NegativeValue from Standard
   ---Purpose: Modifies this ASCII string so that its length
   -- becomes equal to Width and the new characters
   -- are equal to Filler. New characters are added
   -- both at the beginning and at the end of this string.
   -- If Width is less than the length of this ASCII string, nothing happens.
   -- Example
   -- TCollection_AsciiString
   -- myAlphabet("abcdef");
   -- myAlphabet.Center(9,' ');
   -- assert ( myAlphabet == "
   -- abcdef " ); 
   is static;

   ChangeAll(me : out; aChar, NewChar : Character;
           CaseSensitive : Boolean=Standard_True)
   ---Level: Public
   ---Purpose: Substitutes all the characters equal to aChar by NewChar
   -- in the AsciiString <me>.
   -- The substitution can be case sensitive.
   -- If you don't use default case sensitive, no matter wether aChar 
   -- is uppercase or not.
   --  Example: me = "Histake" -> ChangeAll('H','M',Standard_True)
   -- gives me = "Mistake"
   is static;

   Clear (me : out)
   ---Level: Public
   ---Purpose: Removes all characters contained in <me>.
   -- This produces an empty AsciiString.
   is static;

   Copy (me : out ; fromwhere : CString from Standard)
   ---Level: Public
   ---Purpose: Copy <fromwhere> to <me>.
   -- Used as operator =
   --  Example: aString = anotherCString;
   ---C++: alias operator =
   is static;

   Copy (me : out ; fromwhere : AsciiString from TCollection)
   ---Level: Public
   ---Purpose: Copy <fromwhere> to <me>.
   -- Used as operator =
   --  Example: aString = anotherString;
   ---C++: alias operator =
   is static;

   Destroy (me : in out)
   ---Level: Public
   ---Purpose: Frees memory allocated by AsciiString.
   ---C++: alias ~
   is static;

   FirstLocationInSet(me; Set : AsciiString from TCollection;
                      FromIndex : Integer from Standard; 
                      ToIndex   : Integer from Standard)
   returns Integer
   raises OutOfRange from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns the index of the first character of <me> that is 
   -- present in <Set>.
   -- The search begins to the index FromIndex and ends to the
   -- the index ToIndex.
   -- Returns zero if failure.
   -- Raises an exception if FromIndex or ToIndex is out of range.
   --  Example: before 
   --   me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
   -- after
   --   me = "aabAcAa"
   -- returns
   --   1

   FirstLocationNotInSet(me; Set : AsciiString from TCollection;
                         FromIndex : Integer; 
                         ToIndex   : Integer) returns Integer
   raises OutOfRange from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns the index of the first character of <me> 
   -- that is not present in the set <Set>.
   -- The search begins to the index FromIndex and ends to the
   -- the index ToIndex in <me>.
   -- Returns zero if failure.
   -- Raises an exception if FromIndex or ToIndex is out of range.
   --  Example: before 
   --   me = "aabAcAa", S = "Aa", FromIndex = 1, Toindex = 7
   -- after
   --   me = "aabAcAa"
   -- returns
   --   3

   Insert (me : out; where : Integer; what : Character)
   ---Level: Public
   ---Purpose: Inserts a Character at position <where>.
   --  Example:
   --    aString contains "hy not ?"
   --    aString.Insert(1,'W'); gives "Why not ?"
   --    aString contains "Wh"
   --    aString.Insert(3,'y'); gives "Why"
   --    aString contains "Way"
   --    aString.Insert(2,'h'); gives "Why"
   raises OutOfRange from Standard
   is static;

   Insert (me : out; where : Integer; what : CString)
   ---Level: Public
   ---Purpose: Inserts a CString at position <where>.
   --  Example:
   --    aString contains "O more"
   --    aString.Insert(2,"nce");  gives "Once more"
   raises NullObject from Standard, 
          OutOfRange from Standard
   is static;

   Insert (me : out; where : Integer; what : AsciiString from TCollection)
   ---Level: Public
   ---Purpose: Inserts a AsciiString at position <where>.
   raises OutOfRange;

   InsertAfter(me : out; Index : Integer; 
               other : AsciiString from TCollection)
   raises OutOfRange from Standard
   is static;
   ---Level: Public
   ---Purpose: Pushing a string after a specific index in the string <me>.
   -- Raises an exception if Index is out of bounds.
   -- -   less than 0 (InsertAfter), or less than 1 (InsertBefore), or
   -- -   greater than the number of characters in this ASCII string.
   --  Example:
   -- before
   --   me = "cde" , Index = 0 , other = "ab"  
   -- after
   --   me = "abcde" , other = "ab"

   InsertBefore(me : out; Index : Integer; 
                other : AsciiString from TCollection)
   raises OutOfRange from Standard
   is static;
   ---Level: Public
   ---Purpose: Pushing a string before a specific index in the string <me>.
   -- Raises an exception if Index is out of bounds.
   -- -   less than 0 (InsertAfter), or less than 1 (InsertBefore), or
   -- -   greater than the number of characters in this ASCII string.
   --  Example:
   -- before
   --   me = "cde" , Index = 1 , other = "ab"  
   -- after
   --   me = "abcde" , other = "ab"

   IsEmpty(me) returns Boolean from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns True if the string <me> contains zero character.

   IsEqual (me ; other : CString) returns Boolean
   ---Purpose:  Returns true if the characters in this ASCII string
    -- are identical to the characters in ASCII string other.
    -- Note that this method is an alias of operator ==.
   raises NullObject from Standard
   is static;
   ---C++: alias operator ==

   IsEqual (me ; other : AsciiString from TCollection) 
   returns Boolean from Standard
   is static;
   ---Purpose:  Returns true if the characters in this ASCII string
    -- are identical to the characters in ASCII string other.
    -- Note that this method is an alias of operator ==.
   ---C++: alias operator ==
 
   IsDifferent (me ; other : CString) 
   returns Boolean from Standard
   ---Level: Public
   ---Purpose:  Returns true if there are differences between the
   -- characters in this ASCII string and ASCII string other.
   -- Note that this method is an alias of operator !=
   raises NullObject from Standard
   is static;
   ---C++: alias operator !=

   IsDifferent (me ; other : AsciiString from TCollection) 
   returns Boolean from Standard
   is static;
   ---Purpose:  Returns true if there are differences between the
   -- characters in this ASCII string and ASCII string other.
   -- Note that this method is an alias of operator !=
   ---C++: alias operator !=

   IsLess (me ; other : CString) returns Boolean from Standard
   ---Level: Public
   ---Purpose: Returns TRUE if <me> is 'ASCII' less than <other>.
   raises NullObject from Standard
   ---C++: alias operator <
   is static;

   IsLess (me ; other : AsciiString from TCollection) 
   returns Boolean from Standard
   ---Level: Public
   ---Purpose: Returns TRUE if <me> is 'ASCII' less than <other>.
   ---C++: alias operator <
   is static;

   IsGreater (me ; other : CString) returns Boolean from Standard
   ---Level: Public
   ---Purpose: Returns TRUE if <me> is 'ASCII' greater than <other>.
   raises NullObject from Standard
   is static;
   ---C++: alias operator >

   IsGreater (me ; other : AsciiString from TCollection) 
   returns Boolean from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns TRUE if <me> is 'ASCII' greater than <other>.
   ---C++: alias operator >

   IntegerValue(me) 
   returns Integer from Standard
   ---Level: Public
   ---Purpose: Converts a AsciiString containing a numeric expression to 
   -- an Integer.
   --  Example: "215" returns 215.
   raises NumericError from Standard
   is static;   

   IsIntegerValue(me) returns Boolean from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns True if the AsciiString contains an integer value.
   -- Note: an integer value is considered to be a real value as well.
   
   IsRealValue(me) returns Boolean from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns True if the AsciiString contains a real value.
   --  Note: an integer value is considered to be a real value as well.

   IsAscii(me) returns Boolean from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns True if the AsciiString contains only ASCII characters
   -- between ' ' and '~'.
   -- This means no control character and no extended ASCII code.
         
   LeftAdjust(me :  out)
   is static;
   ---Level: Public
   ---Purpose: Removes all space characters in the begining of the string.

   LeftJustify(me : out; Width : Integer; 
               Filler : Character from Standard) 
   raises NegativeValue from Standard
   is static;
   ---Level: Public
   ---Purpose: left justify
   -- Length becomes equal to Width and the new characters are
   -- equal to Filler.
   -- If Width < Length nothing happens.
   -- Raises an exception if Width is less than zero.
   --  Example:
   -- before
   --   me = "abcdef" , Width = 9 , Filler = ' '
   -- after
   --   me = "abcdef   " 

   Length (me) returns Integer
   is static;
   ---C++: inline
   ---Level: Public
   ---Purpose: Returns number of characters in <me>.
   -- This is the same functionality as 'strlen' in C.
   -- Example
   --  TCollection_AsciiString myAlphabet("abcdef");
   -- assert ( myAlphabet.Length() == 6 );
   -- -   1 is the position of the first character in this string.
   -- -   The length of this string gives the position of its last character.
   -- -   Positions less than or equal to zero, or
   --   greater than the length of this string are
   --   invalid in functions which identify a character
   --   of this string by its position.
 
   Location(me; other : AsciiString from TCollection;
            FromIndex : Integer; 
            ToIndex   : Integer) 
   returns Integer from Standard
   raises OutOfRange from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns an index in the string <me> of the first occurence
   -- of the string S in the string <me> from the starting index
   -- FromIndex to the ending index ToIndex
   -- returns zero if failure
   -- Raises an exception if FromIndex or ToIndex is out of range.
   --  Example: 
   -- before 
   --   me = "aabAaAa", S = "Aa", FromIndex = 1, ToIndex = 7
   -- after
   --   me = "aabAaAa"
   -- returns
   --   4

   Location(me; N : Integer; C : Character from Standard; 
            FromIndex : Integer; 
            ToIndex   : Integer) 
   returns Integer from Standard
   raises OutOfRange from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns the index of the nth occurence of the character C
   -- in the string <me> from the starting index FromIndex to the
   -- ending index ToIndex.
   -- Returns zero if failure.
   -- Raises an exception if FromIndex or ToIndex is out of range.
   --  Example:
   -- before 
   --   me = "aabAa", N = 3, C = 'a', FromIndex = 1, ToIndex = 5
   -- after
   --   me = "aabAa"
   -- returns
   --   5

   LowerCase (me : out)
   is static;
   ---Level: Public
   ---Purpose: Converts <me> to its lower-case equivalent.
   -- Example
   -- TCollection_AsciiString myString("Hello Dolly");
   -- myString.UpperCase();
   -- assert ( myString == "HELLO DOLLY" );
   -- myString.LowerCase();
   -- assert ( myString == "hello dolly" );

   Prepend(me : out; other : AsciiString from TCollection)
   is static;
   ---Level: Public
   ---Purpose: Inserts the string other at the beginning of this ASCII string.
   -- Example
   -- TCollection_AsciiString myAlphabet("cde");
   -- TCollection_AsciiString myBegin("ab");
   -- myAlphabet.Prepend(myBegin);
   -- assert ( myAlphabet == "abcde" );

   Print (me ; astream : out OStream)
   is static;
   ---Level: Public
   ---Purpose: Displays <me> on a stream.
   ---C++: alias "friend Standard_EXPORT Standard_OStream& operator << (Standard_OStream& astream,const TCollection_AsciiString& astring);"

   Read (me : out; astream : out IStream)
   is static;
   ---Level: Public
   ---Purpose: Read <me> from a stream.
   ---C++: alias "friend Standard_EXPORT Standard_IStream& operator >> (Standard_IStream& astream, TCollection_AsciiString& astring);"

   RealValue(me) returns Real from Standard
   ---Level: Public
   ---Purpose: Converts an AsciiString containing a numeric expression.
   -- to a Real.
   --  Example: ex: "215" returns 215.0.
   -- ex: "3.14159267" returns 3.14159267.
   raises NumericError from Standard
   is static;

   RemoveAll(me :out; C : Character from Standard;
             CaseSensitive : Boolean from Standard)
   is static;
   ---Level: Public
   ---Purpose: Remove all the occurences of the character C in the string.
   --  Example:
   -- before
   --   me = "HellLLo", C = 'L' , CaseSensitive = True
   -- after
   --   me = "Hello"

   RemoveAll(me : out; what : Character)
   is static;
   ---Level: Public
   ---Purpose: Removes every <what> characters from <me>.

   Remove (me : out ; where : Integer ; ahowmany : Integer=1)
   ---Level: Public
   ---Purpose: Erases <ahowmany> characters from position <where>,
   -- <where> included.
   --  Example:
   --   aString contains "Hello"
   --   aString.Remove(2,2) erases 2 characters from position 2
   -- This gives "Hlo".
   raises OutOfRange from Standard
   is static;

   RightAdjust(me : out)
   is static;
   ---Level: Public
   ---Purpose: Removes all space characters at the end of the string.

   RightJustify(me : out; 
                Width : Integer;
                Filler : Character from Standard) 
   raises NegativeValue from Standard
   is static;
   ---Level: Public
   ---Purpose: Right justify.
   -- Length becomes equal to Width and the new characters are
   -- equal to Filler.
   -- if Width < Length nothing happens.
   -- Raises an exception if Width is less than zero.
   --  Example:
   -- before
   --   me = "abcdef" , Width = 9 , Filler = ' '
   -- after
   --   me = "   abcdef" 


   Search (me ; what : CString) returns Integer from Standard
   ---Level: Public
   ---Purpose: Searches a CString in <me> from the beginning 
   -- and returns position of first item <what> matching.
   -- it returns -1 if not found.
   --  Example:     
   --  aString contains "Sample single test"
   --  aString.Search("le") returns 5
   raises NullObject from Standard
   is static;

   Search (me ; what : AsciiString from TCollection) 
   returns Integer from Standard
   is static;
   ---Level: Public
   ---Purpose: Searches an AsciiString in <me> from the beginning 
   -- and returns position of first item <what> matching.
   -- It returns -1 if not found.

   SearchFromEnd (me ; what : CString) 
   returns Integer from Standard
   ---Level: Public
   ---Purpose: Searches a CString in a AsciiString from the end 
   -- and returns position of first item <what> matching.
   -- It returns -1 if not found.
   --  Example:
   --  aString contains "Sample single test"
   --  aString.SearchFromEnd("le") returns 12
   raises NullObject from Standard
   is static;

   SearchFromEnd (me ; what : AsciiString from TCollection) 
   returns Integer from Standard
   is static;
   ---Level: Public
   ---Purpose: Searches a AsciiString in another AsciiString from the end 
   -- and returns position of first item <what> matching.
   -- It returns -1 if not found.

   SetValue(me : out; where : Integer; what : Character)
   ---Level: Public
   ---Purpose: Replaces one character in the AsciiString at position <where>.
   -- If <where> is less than zero or greater than the length of <me>
   -- an exception is raised.
   --  Example:  
   -- aString contains "Garbake"
   -- astring.Replace(6,'g')  gives <me> = "Garbage"
   raises OutOfRange from Standard
   is static;

   SetValue(me : out; where : Integer; what : CString)
   ---Level: Public
   ---Purpose: Replaces a part of <me> by a CString.
   -- If <where> is less than zero or greater than the length of <me>
   -- an exception is raised.
   --  Example: 
   --  aString contains "abcde"
   --  aString.SetValue(4,"1234567") gives <me> = "abc1234567"
   raises OutOfRange from Standard
   is static;

   SetValue(me : out; where : Integer; what : AsciiString from TCollection)
   ---Level: Public
   ---Purpose: Replaces a part of <me> by another AsciiString.
   raises OutOfRange from Standard
   is static;

   Split(me : out; where : Integer; result : out AsciiString from TCollection)
   is private; 

   Split(me : out; where : Integer) 
   returns AsciiString from TCollection
   ---Level: Public
   ---Purpose: Splits a AsciiString into two sub-strings.
   --  Example: 
   -- aString contains "abcdefg"
   -- aString.Split(3) gives <me> = "abc" and returns "defg"
   raises OutOfRange from Standard
   is static;

   
   SubString(me; FromIndex, ToIndex : Integer;
                 result : out AsciiString from TCollection)
   is private;
   
   SubString(me; FromIndex, ToIndex : Integer) 
   ---Level: Public
   ---Purpose: Creation of a sub-string of the string <me>.
   -- The sub-string starts to the index Fromindex and ends
   -- to the index ToIndex.
   -- Raises an exception if ToIndex or FromIndex is out of bounds
   --  Example: 
   -- before
   --   me = "abcdefg", ToIndex=3, FromIndex=6
   -- after
   --   me = "abcdefg"
   -- returns
   --   "cdef"
   ---C++: inline
   returns AsciiString from TCollection
   raises OutOfRange from Standard
   is static;

   ToCString(me) 
   returns CString from Standard
   is static;
   ---Level: Public
   ---Purpose: Returns pointer to AsciiString (char *).
   -- This is useful for some casual manipulations.
   --  Warning: Because this "char *" is 'const', you can't modify its contents.
   ---C++: inline

   Token (me ; separators : CString ;
               whichone   : Integer;
               result     : out AsciiString from TCollection)
   is private;
   
   Token (me ; separators : CString=" \t" ; whichone : Integer=1) 
   returns AsciiString from TCollection
   ---Level: Public
   ---Purpose: Extracts <whichone> token from <me>.
   -- By default, the <separators> is set to space and tabulation.
   -- By default, the token extracted is the first one (whichone = 1).
   -- <separators> contains all separators you need.
   -- If no token indexed by <whichone> is found, it returns empty AsciiString.
   --  Example:
   --    aString contains "This is a     message"
   --    aString.Token()  returns "This" 
   --    aString.Token(" ",4) returns "message"
   --    aString.Token(" ",2) returns "is"
   --    aString.Token(" ",9) returns ""
   -- Other separators than space character and tabulation are allowed :
   --    aString contains "1234; test:message   , value"
   --    aString.Token("; :,",4) returns "value"
   --    aString.Token("; :,",2) returns "test"
   raises NullObject from Standard
   is static;

   Trunc (me : out ; ahowmany  : Integer)
   ---Level: Public
   ---Purpose: Truncates <me> to <ahowmany> characters.
   --  Example:  me = "Hello Dolly" -> Trunc(3) -> me = "Hel"
   raises OutOfRange from Standard
   is static;

   UpperCase (me : out)
   is static;
   ---Level: Public
   ---Purpose: Converts <me> to its upper-case equivalent.

   UsefullLength(me) 
   returns Integer from Standard
   is static;
   ---Level: Public
   ---Purpose: Length of the string ignoring all spaces (' ') and the 
   -- control character at the end.

   Value(me ; where : Integer) 
   returns Character from Standard
   ---Level: Public
   ---Purpose: Returns character at position <where> in <me>.
   -- If <where> is less than zero or greater than the lenght of <me>, 
   -- an exception is raised.
   --  Example: 
   --    aString contains "Hello"
   --    aString.Value(2) returns 'e'
   raises OutOfRange from Standard
   is static;
 
   HashCode(myclass ; astring : AsciiString from TCollection; Upper : Integer)
   returns Integer;
   ---Level: Internal
   ---Purpose: Hash function for AsciiString 
   --  (returns the same Integer value that the hash function for ExtendedString)
   ---C++: inline

   IsEqual(myclass ; string1 : AsciiString from TCollection; 
           string2 : AsciiString from TCollection)
   returns Boolean;
   ---Level: Internal
   ---Purpose: Returns True  when the two  strings are the same. 
   --          (Just for HashCode for AsciiString)
   ---C++: inline

   IsEqual(myclass ; string1 : AsciiString from TCollection; 
           string2 : CString from Standard)
   returns Boolean;
   ---Level: Internal
   ---Purpose: Returns True  when the two  strings are the same. 
   --          (Just for HashCode for AsciiString)
   ---C++: inline

   HASHCODE(myclass ; astring : AsciiString from TCollection; Upper : Integer)
   returns Integer;
   ---Level: Internal
   ---Purpose: Hash function for AsciiString no case sensitive
   ---C++: inline

   ISSIMILAR(myclass ; string1 : AsciiString from TCollection; 
             string2 : AsciiString from TCollection)
   returns Boolean;
   ---Level: Internal
   ---Purpose: Returns True  when the two  strings are the same
   --          (no case sensitive). 
   --          (Just for HashCode for AsciiString)
    
         
fields
  mystring      : PCharacter; 
  mylength      : Integer;

friends
    class HAsciiString from TCollection
end AsciiString from TCollection;