– Typee Documentation –

3 – Typee Language Description

3.15 – Typee strings

Before explaining Typee built-in containers in next section, we describe here strings in Typee. These are somewhat like containers: they contain items (characters), they can be indexed, operations are available on them as well as built-in functions are applicable to them also. Let’s review all of this here.

3.15.1 str and str16

There are two built-in types for strings in typee: str and str16. The former exclusively contains 8-bits characters of type char. The latter exclusively contains 16-bits characters of type char16.

No mixing of these two types is allowed with built-in operators and functions. It is not legal to assign an str string with an str16 one for instance. It is not legal also to concatenate strings of different types.
In any of these cases, a TypeException will be raised or, if detectable at translation time, an error will be set by translators.

3.15.2 Strings operators

3.15.2.1 Concatenation

Concatenation is the appending of a string to the end of another one.

const str operator + ( const ? in (char,str) left, const ? in (char,str) right )

const str16 operator + ( const ? in (char16,str16) left, const ? in (char16,str16) right )

Creates a new not mutable string which is the concatenation of left then right.
Returns a reference to this newly created string.
Example:

const str s1 = "ABCD";
const str s2 = "0123";
print( s1, s2, s1+s2 );  // prints:  ABCD 0123 ABCD0123

str operator += ( str left, const ? in (char,str) right )

str16 operator += ( str16 left, const ? in (char16,str16) right )

Modifies the content of left by appending at its end the content of right.
Returns a reference to left.
Example:

str s1 = "ABCD";
const str s2 = "0123";
print( s1, s2 );  // prints:  ABCD 0123
s1 += s2;
print( s1, s2 );  // prints:  ABCD0123 0123

3.15.2.2 Indexing strings

Indexing is divided in two sub-modes: returning the contained character as a constant value and returning a reference to it.
When its constant value is returned, the character can only be read and cannot be modified internally within the string. When a reference to it is returned, the character value may be modified within the string.

const char operator [] ( const str s, const int64 index )

const char16 operator [] ( const str16 s, const int64 index )

Indexing starts at 0. Negative indexing is allowed: index -1 points to the last character contained in the string.
Returns the value of the indexed character as a non mutable value.
Raises OutOfBoundsException if index is out of bounds.
Examples:

const str s4 = "ABCD";
// read-only chars: const version of operator is called here
print( s[0], s[3], s[-1], s[-4] ),  // prints: A D D A

char operator [] ( str s, const int64 index )

char16 operator [] ( str16 s, const int64 index )

Indexing starts at 0. Negative indexing is allowed: index -1 points to the last character contained in the string.
Returns the reference to the indexed character as a mutable value within the containing string.
Raises OutOfBoundsException if index is out of bounds.
Examples:

const str s1 = "ABCD";
str s2 = s1;
s2[1] = '1';
print( s1, s2 );  // prints:  ABCD A1CD

3.15.2.3 Slicing in strings

Slicing is divided in two sub-modes: returning the contained characters with constant values and returning a reference to them.
When their constant values are returned, the characters can only be read and cannot be modified internally within the string. When a reference to them is returned, the characters values may be modified within the string.

const str operator [] ( const str s, const slice slc )

const str16 operator [] ( const str16 s, const slice slc )

Indexing starts at 0. Negative indexing is allowed: index -1 points to the last character contained in the string.
Returns a not mutable string that contains the sliced characters of the operated string.
Raises OutOfBoundsException if any index in slice is out of bounds.
Examples:

const str s4 = "ABCD";

print( s[0:3:2], s[-1::-1] ),  // prints: AC DCBA

str operator [] ( str s, const slice slc )

str16 operator [] ( str16 s, const slice slc )

Indexing starts at 0. Negative indexing is allowed: index -1 points to the last character contained in the string.
Returns a reference to a new mutable string.
Raises OutOfBoundsException if index is out of bounds.
Examples:

const str s1 = "ABCD";
str s2 = s1[-1:1:-1];
print( s1, s2 );  // prints:  DCB
s2[1] = '1';
print( s1, s2 );  // prints:  D1B

3.15.2.4 Copy and Reference

The assign operator = copies the content of a string into antoher string. To create a reference to a string, this string must be preceded by unary operator &. It can then be assigned its reference to another string.
Example:

const str s1 = "ABCD";
str s2, s3;
s2 = s1;
print( s1, s2 );      // prints: ABCD ABCD
s2[2] = '2';
print( s1, s2 );      // prints: ABCD AB2D
//s3 = &s1;           // would raise an error on types
s3 = &s2;
s3[0] = '0';
print( s1, s2, s3 );  // prints: ABCD 0B2D 0B2D

3.15.2.5 Removing patterns from string

The remove operator - removes all found patterns from an operated string.

str operator – ( str s, const ? in (char,str) pattern )

str16 operator – ( str16 s, const ? in (char16,str16) pattern )

Creates a new mutable string with s and suppresses pattern from this new string if pattern has been found in it.
If pattern is not found, returns a reference to the newly created string with no modification from s.
Examples:

str s = "ABCDefghABCD0123";
print( s - "gh" <- "12" );  // prints: ABCDefABCD03

str operator -= ( const ? in (char,str) pattern )

str16 operator -= ( const ? in (char16, str16) pattern )

Suppresses from the operated string every pattern found in it.
If pattern is not found, returns a reference to string with no modification.
Returns a reference to the operated string.
Examples:

str s = "ABCDefghABCD0123";
s -= "ABC";
print( s );  // prints: DefghD0123

3.15.2.6 Searching for a sub-string in a string

const bool operator in ( const str left, const ? in (char,str) right )

const bool operator in ( const str16 left, const ? in (char16,str16) right )

Returns true if sub-string right is present in string left and false otherwise.

const bool operator not in ( const str left, const ? in (char,str) right )

const bool operator not in ( const str16 left, const ? in (char16,str16) right )

Returns false if sub-string right is present in string left and true otherwise.

Examples:

const str s = "ABCDefghABCD0123";
print( "BCD" in s );      // prints: true
print( "FGh" in s );      // prints: false
print( "BCD" not in s );  // prints: false
print( "FGh" not in s );  // prints: true

3.15.2.7 Comparison of strings

All the comparison operators are defined on strings in Typee:
< <= == != >= > <=> . Reminder: comparison operator <=> returns a negative integer value if left operand is less than right operand, a zero value if both operands are equal and a positive integer value if left operand is greater than right operand.
Comparisons are done on in-place characters. They are case-sensitive (have a look to built-in functions to_lower() and to_upper() to be able to compare strings without case sensitivity).
When comparing strings of different lengths, comparison is nevertheless done on the characters starting at position 0 in both strings. If these two strings compare the same according to the shortest one, i.e. they both contain the same characters up to the shortest length, then the shorter string is evaluated as less than the longer one.

3.15.3 Strings functions

Typee built-in functions that are related to strings are applicable to strings as would be methods of classes. They may also be applied to string literals the same way.

We explain here all of those built-in functions.

3.15.3.1 String length

How many characters are in a string? What is the siez in memory space of a string?

const uint64 count()

Returns the number of characters contained within a string.
Example:

str   s   = "0123456789";
str16 s16 = "0123456789";
print( s.count(), s16.count() );
// prints:  10 10
print( "0123456789".count(), str16("0123456789").count() );
// prints:  10 10

const uint64 size()

Returns the number of bytes of memory occupied by the content of a string.
Example:

str   s   = "0123456789";
str16 s16 = "0123456789";
print( s.size(), s16.size() );
// prints:  10 20
print( "0123456789".size(), str16("0123456789").size() );
// prints:  10 20

3.15.3.2 Filling strings

Fills strings with a character or a pattern.

str fill( const ? in (char,str) pattern )

str16 fill( const ? in (char16,str16) pattern )

str fill( const ? in (char,str) pattern, const uint64 nb_copies )

str16 fill( const ? in (char16,str16) pattern, const uint64 nb_copies )

Fills the operated string with the specified pattern.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
When nb_copies is unspecified, its value defaults to 1. The specified pattern is used nb_copies times to fill the operated string.
Returns a reference to the operated string.
Example:

str s;
s.fill( "aabb", 3 );
print( s );  // prints:  aabbaabbaabb
s.fill( "0123456789", 2 )[1] = '#'
print( s );  // prints:  0#234567890123456789

3.15.3.3 Finding patterns in strings

str find( const ? in (char,str) pattern )

str16 find( const ? in (char16,str16) pattern )

Searches for pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
When pattern is found, returns a mutable reference to the first character of the first occurence of pattern. Returns none otherwise.
Example:

const str s = "ABCDefghABCD0123";
s.find( 'B' ) = "*#*";
print( s );              // prints: A*#*efghABCD0123
print( s.find("EFG") );  // prints: none

list<str> find( const ? in (char,str) pattern, const uint64 nb )

list<str16> find( const ? in (char16,str16) pattern, const uint64 nb )

Searches for pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a list of references of the nb first occurences of the pattern within the operated string. Returns an empty list [] otherwise.
Example:

const str s = "ABCDefghABCD0123";
for( str ref_p in s.find( "BC", 3 ) )
    ref_p = "*#*";
print( s );  // prints:  A*#*efghA*#*0123

list<str> find_all( const ? in (char,str) pattern, const uint64 nb )

list<str16> find_all( const ? in (char16,str) pattern, const uint64 nb )

Searches for pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a list of all references of the pattern within the operated string. Returns an empty list [] when pattern is not found.
Example:

const str s = "ABCDefghABCD0123";
for( str ref_p in s.find_all("BC") )
    ref_p = "*#*";
print( s );  // prints:  A*#*efghA*#*0123

str reverse_find( const ? in (char,str) pattern )

str16 reverse_find( const ? in (char16,str16) pattern )

Searches for pattern in the operated string, starting at character at end of string, in reverse order.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
When pattern is found, returns a mutable reference to the first character of the last occurence of pattern. Returns none otherwise.
Example:

const str s = "ABCDefghABCD0123";
s.reverse_find( 'B' ) = "*#*";
print( s );              // prints: ABCDefghA*#*0123
print( s.find("EFG") );  // prints: none

list<str> reverse_find( const ? in (char,str) pattern, const uint64 nb )

list<str16> reverse_find( const ? in (char16,str16) pattern, const uint64 nb )

Searches for pattern in the operated string, starting at end of string, in reverse order.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a list of references of the nb last occurences of the pattern within the operated string. Returns an empty list [] otherwise.
Example:

const str s = "ABCDefghABCD0123";
for( str ref_p in s.reverse_find( "BC", 3 ) )
    ref_p = "*#*";
print( s );  // prints:  A*#*efghA*#*0123

Notice: there is no version of revere_find_all() function. Call find_all() instead.

const uint64 index( const ? in (char,str) pattern )

const uint64 index( const ? in (char16,str16) pattern )

Searches for pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
When pattern is found, returns the index in the string of the first character of the first occurence of pattern. Raises NotFoundException otherwise. Operator in as well as not in should then be used before calling index(), or the call to index() should be done in a try statement.
Example:

const str s = "ABCDefghABCD0123";
print( s.index('B') );        // prints: 1
print( s.index("efg") );      // prints: 4
try {
    print( s.index("EFG") );  // raises NotFoundException
}
except Exception as e {
    print( e );               // prints:  NotFoundException raised at line 5
}

list<const uint64> index( const ? in (char,str) pattern, const uint64 nb )

list<const uint64> index( const ? in (char16,str16) pattern, const uint64 nb )

Searches for pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a list of indexes of the nb first occurences of the pattern within the operated string. Returns an empty list [] otherwise.
Notice: does not raise any exception if pattern is not found in string.
Example:

const str s = "ABCDefghABCD0123";
print( s.index( "BC", 3 ) );  // prints:  [1, 9]

list<const uint64> index_all( const ? in (char,str) pattern, const uint64 nb )

list<const uint64> index_all( const ? in (char16,str16) pattern, const uint64 nb )

Searches for pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a list of all indexes of the pattern within the operated string. Returns an empty list [] when pattern is not found.
Notice: does not raise any exception if pattern is not found in string.
Example:

const str s = "ABCDefghABCD0123";
print( s.index_all( "BC" ) );   // prints:  [1, 9]
print( s.index_all( "EFg" ) );  // prints:  []

const uint64 reverse_index( const ? in (char,str) pattern )

const uint64 reverse_index( const ? in (char16,str16) pattern )

Searches for pattern in the operated string, starting at character at end of string, in reverse order.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
When pattern is found, returns the index in the string of the first character of the last occurence of pattern. Raises NotFoundException otherwise. Operator in as well as not in should then be used before asking for reverse_index(), or the call to reverse_index() should be done in a try statement.
Example:

const str s = "ABCDefghABCD0123";
print( s.reverse_index('B') );    // prints: 9
print( s.reverse_index("efg") );  // prints: 4
try {
    print( s.index("EFG") );  // raises NotFoundException
}
except Exception as e {
    print( e );               // prints:  NotFoundException raised at line 5
}

list<const uint64> reverse_index( const ? in (char,str) pattern, const uint64 nb )

list<const uint64> reverse_index( const ? in (char16,str16) pattern, const uint64 nb )

Searches for pattern in the operated string, starting at end of string, in reverse order.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a list of indexes of the nb last occurences of the pattern within the operated string. Returns an empty list [] otherwise.
Notice: does not raise any exception if pattern is not found in string.
Example:

const str s = "ABCDefghABCD0123";
print( s.reverse_index( "BC", 3 ) );   // prints:  [9, 1]
print( s.reverse_index( "EFg", 3 ) );  // prints:  []

Notice: there is no version of revere_index_all() function. Call index_all() instead.

3.15.3.4 Inserting strings

Inserts a character or a string pattern into an operated string.

str insert( const uint64 index, const ? in (char,str) sub_str )

str16 insert( const uint64 index, const ? in (char16,str16) sub_str )

Inserts in-place and before specified index a pattern sub_str into the operated string.
sub_str may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars). index starts at 0. Negative values are allowed: -1 indexes the last character of the operated string.
Inserting with index value 0 just inserts the pattern at the beginning of the string.
Inserting with index value 1 just inserts the pattern before the last character of the string.
To append a pattern at the end of a string, use operators + or +=.
Returns a reference to the operated string, for this operation to be cascadable.
Raises OutOfBoundsException if index is out of bounds of the operated string.
Example:

str s = "ABCDefghABCD0123";
print( s.insert( 3, "bc" ) );
  // prints:  ABCbcDefghABCD0123
print( s.insert( 0, "begin" ) );
  // prints:  beginABCbcDefghABCD0123
print( s.insert( -1, "-near end-" ) );
  // prints:  beginABCbcDefghABCD012-near end-3
s += "-true end"
print( s );
  // prints:  beginABCbcDefghABCD012-near end-3-true end

3.15.3.5 Checking emptyness of strings

const bool is_empty()

Checks if a string is empty or not.
Returns true if string is empty and false otherwise.
Examples:

str   s1 = "a not empty string";
str16 s2 = '';
str   s3;
print( s1.is_empty(), s2.is_empty(), s3.is_empty() );
  // prints:  false true true

3.15.3.6 Removing patterns from strings

str remove( const ? in (char,str) pattern )

str16 remove( const ? in (char16,str16) pattern )

Removes in-place the first occurence of pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123";
print( s.remove('BC') );   // prints: ADefghABCD0123
print( s.remove("efg") );  // prints: ADhABCD0123
print( s.remove("EFG") );  // prints: ADhABCD0123

str remove( const ? in (char,str) pattern, const uint64 nb )

str16 remove( const ? in (char16,str) pattern, const uint64 nb )

Removes in-place the nb first occurences of pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123ABCD";
print( s.remove('BC', 2).remove('12', 2) );   // prints: ADefghAD03ABCD

str remove_all( const ? in (char,str) pattern )

str16 remove_all( const ? in (char16,str16) pattern )

Removes in-place all the occurences of pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123ABCD";
print( s.remove_all( "BC" ) );   // prints:  ADefghAD0123AD
print( s.remove_all( "EFg" ) );  // prints:  ADefghAD0123AD

Notice: remove_all() gets same behavior as operator -.

str reverse_remove( const ? in (char,str) pattern )

str16 reverse_remove( const ? in (char16,str16) pattern )

Removes in-place the last occurence of pattern in the operated string, starting at character at end of string, in reverse order.
pattern may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

 str s = "ABCDefghABCD0123";
print( s.reverse_remove('B') );    // prints: ABCDefghACD0123
print( s.reverse_remove("efg") );  // prints:  ABCDhACD0123
print( s.reverse_remove("EFG") );  // prints:  ABCDhACD0123

str reverse_remove( const ? in (char,str) pattern, const uint64 nb )

str16 reverse_remove( const ? in (char16,str16) pattern, const uint64 nb )

Removes in-place the nb last occurences of pattern in the operated string, starting at character at end of string, in reverse order.
pattern may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

 str s = "ABCDefghABCD0123ABCD";
print( s.reverse_remove('B', 2) );    // prints:  ABCDefghACD0123ACD
print( s.reverse_remove("efg", 2) );  // prints:  ABCDhACD0123ACD
print( s.reverse_remove("EFG", 8) );  // prints:  ABCDhACD0123ACD

Notice: there is no version of revere_remove_all() function. Call remove_all() instead.

3.15.3.7 Replacing patterns within strings

str replace( const ? in (char,str) pattern, const ? in (char,str) new_pattern )

str16 replace( const ? in (char16,str16) pattern, const ? in (char16,str16) new_pattern )

Replaces in-place the first occurence of pattern in the operated string with new_pattern, starting at character of index 0.
pattern and new_pattern may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123";
print( s.replace('BC', "xyz") );      // prints: AxyzDefghABCD0123
print( s.replace("efg", "EFG") );     // prints: AxyzDEFGhABCD0123
print( s.replace("hAz", , "###")) );  // prints: AxyzDEFGhABCD0123
print( s.replace("xyz", , "#")) );    // prints: A#DEFGhABCD0123

str replace( const ? in (char,str) pattern, const ? in (char,str) new_pattern, const uint64 nb )

str16 replace( const ? in (char16,str16) pattern, const ? in (char16,str16) new_pattern, const uint64 nb )

Replaces in-place the nb first occurences of pattern with new_pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string, of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123ABCD";
print( s.replace('BC', '#', 2).replace('12', 'BC', 2) );
  // prints: A#DefghA#D0BC3ABCD

str replace_all( const ? in (char,str) pattern, const ? in (char,str) new_pattern )

str16 replace_all( const ? in (char16,str16) pattern, const ? in (char16,str16) new_pattern )

Replaces in-place all the occurences of pattern in the operated string with new_pattern in the operated string, starting at character of index 0.
pattern may be either a character or a string of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123ABCD";
print( s.replace_all( "BC", "CB" ) );  // prints:  ACBDefghACBD0123ACBD
print( s.replace_all( "EFg", "#" ) );  // prints:  ACBDefghACBD0123ACBD

str reverse_replace( const ? in (char,str) pattern, const ? in (char,str) new_pattern )

str16 reverse_replace( const ? in (char16,str16) pattern, const ? in (char16,str16) new_pattern )

Replaces in-place the last occurence of pattern in the operated string with new_pattern, starting at character at end of string, in reverse order.
pattern and new_pattern may be either a character or a string, both of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123";
print( s.reverse_replace('B', '#') );     // prints: ABCDefghA#CD0123
print( s.reverse_replace("efg", '##') );  // prints:  ABCD##hA#CD0123
print( s.reverse_replace("EFG", '%%') );  // prints:  ABCD##hA#CD0123

str reverse_replace( const ? in (char,str) pattern, const ? in (char,str) new_pattern, const uint64 nb )

str16 reverse_replace( const ? in (char16,str16) pattern, const ? in (char16,str16) new_pattern, const uint64 nb )

Replaces in-place the nb last occurences of pattern with new_pattern in the operated string, starting at character at end of string, in reverse order.
pattern and new_pattern may be either a character or a string, both of the same kind than the operated string (i.e. 8- or 16- bits chars).
Returns a reference to the operated string, for this function to be cascadable with other string functions and operators.
Example:

str s = "ABCDefghABCD0123ABCD";
print( s.reverse_replace('B', '##', 2) );     // prints:  ABCDefghA##CD0123A##CD
print( s.reverse_replace("efg", '%%', 2) );   // prints:  ABCD%%hA##CD0123A##CD
print( s.reverse_replace("EFG", '---', 8) );  // prints:  ABCD%%hA##CD0123A##CD

3.15.3.8 Splitting strings

list<str> split()

list<str16> split()

list<str> split( const ? in (char,str) pattern )

list<str16> split( const ? in (char16,str16) pattern )

Creates a list of strings, each separated within the original operated string by pattern. pattern is not inserted in any of the separated strings.
pattern may be either a character or a string, of the same kind than the original operated string (i.e. 8- or 16- bits chars). If pattern is missing, the original operated string is split on any space, tab and newline character, grouped together as a single one when contiguous.
The separated strings are of the same kind than the original operated string.
Returns a reference to the created list.
Example:

const str s = "A simple  \t text.";
print( s.split() );  // prints:  ["A", "simple", "text."]
print( s.split('e') );
// prints:  ["A simpl", "  \t t", "xt."]

3.15.3.9 Upper and Lower cases

str lower()

str16 lower()

Creates a new string of same (8-bits, 16-bits) kind than the operated string with every characters put in their lower-case form.
Returns a reference to the newly created string.
Does not modify the original operated string.
Examples:

const str k_str = "this IS a S1mpl3 tEsT";
print( k_str.lower() );  // prints:  this is a s1mpl3 test

str upper()

str16 upper()

Creates a new string of same (8-bits, 16-bits) kind than the operated string with every characters put in their upper-case form.
Returns a reference to the newly created string.
Does not modify the original operated string.
Examples:

const str k_str = "this IS a S1mpl3 tEsT";
print( k_str.upper() );  // prints:  THIS IS A S1MPL3 TEST

str first_up()

str16 first_up()

Creates a new string of same (8-bits, 16-bits) kind than the operated string with the very first character put in its upper-case form and all other characters put in their lower-case form.
Returns a reference to the newly created string.
Does not modify the original operated string.
Examples:

const str k_str = "this IS a S1mpl3 tEsT";
print( k_str.upper() );  // prints:  This is a s1mpl3 test

str words_up()

str16 words_up()

Creates a new string of same (8-bits, 16-bits) kind than the operated string with the first character of every word put in their upper-case form and every other characters put in their lower-case form.
Returns a reference to the newly created string.
Does not modify the original operated string.
Examples:

const str k_str = "this IS a S1mpl3 tEsT";
print( k_str.upper() );  // prints:  This Is A S1mpl3 Test

3.15.3.10 Removing leading and trailing spaces

str trim()

str16 trim()

Removes in-place all leading and ending space, tab and newline characters from the operated string.
Returns a reference to the operated string for this function to be cascadable.
Examples:

const str test = "  \t\nLet's remove spaces from space!\n\t ";
print( test );
/** prints: ('.' stands for space; tabs are four spaces)
....
Let's remove spaces from space!
.....
**/
str s = test;  // trim() can't be operated on const string
print( s.trim() );
/** prints: ('.' stands for space, tabs are four spaces)
Let's remove spaces from space!
**/

str ltrim()

str16 ltrim()

Removes in-place all leading space, tab and newline characters from the operated string (left-trim).
Returns a reference to the operated string for this function to be cascadable.
Examples:

const str test = "  \t\nLet's remove spaces from space!\n\t ";
print( test );
/** prints: ('.' stands for space, tabs are four spaces)
....
Let's remove spaces from space!
.....
**/
str s = test;  // ltrim() can't be operated on const string
print( s.ltrim() );
/** prints: ('.' stands for space; tabs are four spaces)
Let's remove spaces from space!
.....
**/

str rtrim()

str16 rtrim()

Removes in-place all trailing space, tab and newline characters from the operated string (right-trim).
Returns a reference to the operated string for this function to be cascadable.
Examples:

const str test = "  \t\nLet's remove spaces from space!\n\t ";
print( test );
/** prints: ('.' stands for space, tabs are four spaces)
....
Let's remove spaces from space!
.....
**/
str s = test;  // rtrim() can't be operated on const string
print( s.rtrim() );
/** prints: ('.' stands for space; tabs are four spaces)
....
Let's remove spaces from space!
**/

3.15.3.11 Suppressing end of string

str trunc( const int64 index )

str16 trunc( const int64 index )

Truncates in-pace the string from position specified by index until the end of the string. Index starts at 0. Negative indexing is allowed: index -1 specifies the last character of string. The character at offset index is removed from the operated string.
Returns a reference to the operated string, for this function to be cascadable.
Examples:

const str test = "  \t\nLet's remove spaces from space!\n\t ";
print( test );
/** prints: ('.' stands for space, tabs are four spaces)
....
Let's remove spaces from space!
.....
**/
str s = test;  // trunc() can't be operated on const string
print( s.trunc(15) );
/** prints: ('.' stands for space; tabs are four spaces)
....
Let's remov
**/
print( s.trunc(-2) );
/** prints: ('.' stands for space; tabs are four spaces)
....
Let's rem
**/

3.15.4 Formatting strings

Strings can be formatted. The Typee formatting of string is somewhat copying the Python one, with slight differences and a little bit less possibilities – so, a little bit less complexity. Built-in function format() serves the purpose of formatting strings in Typee.

str format( const ? in (str,str16) frmt, … args )

str16 format( const ? in (str,str16) frmt, … args )

If this function is applied to a string variable, formats in-place the operated string according to the format specified in frmt and to the variable list of arguments.
If it si applied to a string literal, creates a temporary string and formats it according to the format specified in frmt and to the variable list of arguments.
Each of the arguments in args relates to a fromat-item in the frmt string.
Returns a reference to the operated string, for this function to be cascadable.
Returns a reference to the newly created string if applied to a string literal, for it to be assignable to any other string.

The syntax of the formatting string frmt can be formaly specified in an EBNF form:

<format string>         ::= <any char but '{'> <format string>  |
                            '{' [<format field>] <format string>

<format field>          ::= [<item id>] [':' <format item>] '}'

<format item>           ::= [ <field alignment> | <field padding> ]
                            [ <field sign> ]
                            [ <field total width> ]
                            [ '.' <field precision width> ]
                            [ <item type> ]
                        
<field alignment>       ::= '<' | '^' | '>' 
<field padding>         ::= '=' 
<field sign>            ::= '+' | ' ' 
<field total width>     ::= <integer>
<field precision width> ::= <integer>

<integer>               ::= '0'  |  '1' ... '9' ( '0' ... '9' )*

<item id>               ::= <integer>
<item type>             ::= 'b' | 'c' | 'C' | 'd' |
                            'e' | 'E' | 'f' | 'F' |
                            'o' | 's' | 'S' | 'x' | 'X' | '%' 

So, a formatting string contains text (may be empty) and embeds formatting items that are embedded in curly braces: {}. If no } can be found in the formatting string after a detected {, the formatting text will not be considered as a field formatting specifier and will be processed as text, just to be inserted as is in the operated string.

Formatting items contain fields that we describe here after. Examples are provided at the end of this section.

3.15.4.1 Field identifier

Optional.
The is a positive integer number that uniquely identifies one of the arguments provided in args. Numbers are indexes in the list of arguments args. They start at 0. There should be no identifier greater or equal to the number of arguments provided in args. Otherwise, an error will be set at translation time if possible, or an OutOfBoundsException will be raised at run-time.
A same field identifier may be used more than once in a formatting string. The related argument in args will then be used multiple times for the formatting of the string.

The field identifier may be followed by a colon : and a format item, in which case a specific format is specified for the related argument n args. See next sub-section.

3.15.4.2 Format item

Optional.
The formatting of an argument in args may be specified by a format item. This is not mandatory. If not specified, a default formatting will be applied to this argument – see default formatting table at the end of this section.

A format item is introduced by a colon (:) in the format field. It is followed by optional fields specifiers that we describe in next sub-sections: field alignment or field padding, field sign, field total width, field precision width and item type. Those fields are all optional but all must appear with this ordering.

3.15.4.3 Field alignment

Optional. Not be be defined with fiels padding (see next sub-section).
Raises StringFormatException if used in conjunction with field padding.
You may define alignment with one from next control characters:

• < for left alignment;
• > for right alignment;
• ^ for centered alignment;

If not specified, default alignment is applied : this is right alignement for strings and left alignment for numbers.

You may instead define a field padding, for numbers only. See below. You can’t define both alignment and padding.

3.15.4.4 Field padding

Optional. Not to be defined with field alignment (see previous sub-section).
Only applicable to the formatting of numbers.
Raises StringFormatException if used in conjunction with field alignment and if applied to not-numbers arguments.
Specifies such a padding with control character =.
When padding numbers, they are right aligned and prefixed by 0‘s. Padding is done according to the total width of the formatted field.

3.15.4.5 Field sign

Optional.
Only applicable to the formatting of numbers.
Raises StringFormatException if used in conjunction with field alignment and if applied to not-numbers arguments.
Specifies the way a leading sign is to be represented. Control characters are:

• '+': leading + and - are systematically inserted in the formatted string
• ' ': a leading - is inserted in the formatted string before negative values and a leading space is inserted before positive values.

If not specified, only - sign is inserting before negative values. Nothing is inserted before positive values.

3.15.4.5 Field total width

Optional.
Positive integer values only – for those who are used to use negative values to invert the default alignment, use the alignment control characters instead.
Raises StringFormatException if a negative value is specified.
This is the total number of characters that are to be reserved for the whole field formatting. For numbers, for instance, this includes any leading and inserted characters used for the display of the formatted number.
If not specified, the exact length of the formatted value is used instead.
The total width of the field may be followed by a dot '.' and a positive integer. See below.

3.15.4.6 Field precision width

Optional.
Only applicable to the formatting of float numbers.
Positive integer values only.
Raises StringFormatException if a negative value is specified or if applied to not a float value.
This is the number of precision digits that will be inserted in the formated string for the related float value. Trailing 0 are appended at end of fractionnal value as padding values.
If not specified, defaults to 5: up to 5 digits are inserted in the formated string, with no padding 0.

3.15.4.7 Item type

Optional.
If not specified, defaults to the type of the formatted item.
Next table explains what are the control characters and what are their meanings. Only one character may be used per formating item.

control character	description
b	binary integer form, prefixed with '0b'
c	8-bits character
C	16-bits character
d	decimal integer form
e	engineering form, exponent is a multiple of 3 and is inserted after character 'e'
E	engineering form, exponent is a multiple of 3 and is inserted after character 'E'
f	floating form, with only 1 digit for mantissa; exponent is inserted after character 'e'
F	floating form, with only 1 digit for mantissa; exponent is inserted after character 'E'
o	octal integer form, prefixed with '0'
s	8-bits string
S	16-bits string
x	hexadecimal integer form, prefixed with '0x' and with lower-case hexadecimal digits
X	hexadecimal integer form, prefixed with '0x' and with upper-case hexadecimal digits
%	percentage form, value is multiplied by 100.0, default precision width is 2 digits, suffixed with '%'

3.15.4.8 Examples

Here are many examples showing all possibilities, each in one or a few ways.

print( "'first arg: {}, second arg: {}'".format( 123, "abc" ) );
  // prints:  'first arg: 123, second arg: abc'

print( "'multiple {0}s printing same arg ('{0}') {1} {0}'".format( 'time',
                                                                   'over' ) );
  // prints:  'multiple times printing same arg ('time') over time'

print( "'{:b}'".format( 9 ) ):
  // prints:  '0b1001'
print( '"{0:<8b}", "{0:=8b}", "{0:>8b}", "{0:8b}"'.format( 9 ) );
  // prints:  "0b1001  ", " 0b1001 ", "  0b1001", "  0b1001"
print( '"{0:+8b}", "{1:+8b}", "{0: 8b}", "{1: 8b}", "{1:8b}"'.format( 9, -9 ) );
  // prints:  " +0b1001", " -0b1001", "  0b1001", " -0b1001", " -0b1001"
print( "'{:=6d}'".format( 9 ) ):
  // prints:  '000009'
print( "'{:X}', '{:=8X}'".format( 9, 0xbeef ) ):
  // prints:  '0x11', '0x00BEEF'

print( "'{:E}'".format( 9.87e1 ) ):
  // prints:  '0.0987E003'
print( "'{:f}'".format( 9.87e1 ) ):
  // prints:  '98.7'
print( '"{0:<8.3f}", "{0:=8.3f}", "{0:>8.3f}", "{0:8.3f}"'.format( 98.7 ) );
  // prints:  "98.700  ", " 98.700 ", "  98.700", "  98.700"
print( '"{0:+8f}", "{1:+8f}", "{0: 8f}", "{1: 8f}", "{1:8f}"'.format( 98.7,
                                                                     -98.6 ) );
  // prints:  "   +98.7", "   -98.6", "    98.7", "   -98.6", "   -98.6"

const str16 txt = "test text";
print( '"{:S}"'.format( txt ) );
  // prints:  "test text"
print( '"{0:<12S}", "{0:=12S}", "{0:>12S}", "{0:12S}"'.format( txt ) );
  //  prints:  "test text   ", "  test text ", "   test text", "test text   "

print( '"{:%}", "{:8%}"'.format( 0.987, 0.986 ) );
  // prints:  "98.7%", "   98.6%"

3.15.5 Casting strings and String casting

Type casting is allowed in Typee with strings, in both ways: strings may be cast to other types, and other types may be cast to string.

3.15.5.1 Casting strings to integers

const int8 operator cast int8 ( const ? in (char,str,char16,str16) txt )

const int16 operator cast int16 ( const ? in (char,str,char16,str16) txt )

const int32 operator cast int32 ( const ? in (char,str,char16,str16) txt )

const int64 operator cast int64 ( const ? in (char,str,char16,str16) txt )

const uint8 operator cast uint8 ( const ? in (char,str,char16,str16) txt )

const uint16 operator cast uint16 ( const ? in (char,str,char16,str16) txt )

const uint32 operator cast uint32 ( const ? in (char,str,char16,str16) txt )

const uint64 operator cast uint64 ( const ? in (char,str,char16,str16) txt )

Transforms txt to the related typed integer value.
txt must contain a valid specification of an integer.
Returns the related integer value of the specified scalar type, as a not mutable value.
Raises ValueException if txt does not contain a valid integer literal.
Example:

int8 val = int8(" -127   ");     // automatically turned into "const int8()"
print_sep( '', '"', val, '"' );  // prints:  "-127"

Notice: integer type casting is neither allowed with generic scalar types _int_ or _uint_ nor it is with _numeric_.

3.15.5.2 Casting strings to floats

const float32 operator cast float32 ( const ? in (char,str,char16,str16) txt )

const float64 operator cast float64 ( const ? in (char,str,char16,str16) txt )

Transforms txt to the related typed floating point value.
txt must contain a valid specification of a float.
Returns the related floating point value of the specified scalar type, as a not mutable value.
Raises ValueException if txt does not contain a valid floating point literal.

float64 avogadro_number = const float32( " 0.602_214_076e+024" );
print( avogadro_number );  // prints: 6.02214e23

Notice: float type casting is neither allowed with generic scalar type _float_ nor it is with _numeric_.

3.15.5.3 Casting strings to booleans

const bool operator cast bool ( const ? in (char,str,char16,str16) txt )

Transforms txt to the related constant boolean value.
txt must contain a valid specification of a boolean:

• 'true', 'True', 't' or 'T' for true;
• 'false', 'False', 'f' or 'F' for false;

Returns the related boolean value as a not mutable value.
Raises ValueException if txt does not contain a valid boolean literal as expressed above.
Example:

print( bool(' T '), bool(' F'), bool('true'), bool('   False ') );
  // prints: true false true false

3.15.5.4 Casting strings to slices

const slice operator cast slice ( const ? in (char,str,char16,str16) txt )

Transforms txt to the related constant slice object.
txt must contain a valid slice literal specification.
Returns a reference to the related slice.
Raises ValueException if txt does not contain a valid slice literal expression.
Reminder: slices Typee grammar rules are:

<slice literal> ::= '[' <start> ':' [<end> [':' <step>]] ']'
<end>           ::= <integer>
<start>         ::= <integer>
<step>          ::= <integer>

Example:

const str my_slice_txt = " [ 1 : 9 :2]";
print_end( '"' );
for( int8 i in slice(my_slice_txt) )
    print_end( ' ', i );
print( '"' );
// prints:  "1 3 5 7 9 "

3.15.5.5 Casting strings to classes

This is very simple to implement and is inherent to the Object Oriented Programming nature of language Typee.
Defining a constructor with a string as its unique argument will do it!

Example:

class MyClass {
  :public:
    
    uint32 val;
  
    MyClass(){
        me.val = 0;
    }
    MyClass( const str txt ){
        me.val = str( txt );
    }
    MyClass( const str16 txt ){
        me.val = str16( txt );
    }
}

MyClass my_c = MyClass( " 123" ); // looks like casting, but is a constructor
print( my_c.val );                // prints: 123

3.15.5.6 Casting integers to strings

str operator cast str ( const ? in (_int_, _uint_) ) val )

str16 operator cast str16 ( const ? in (_int_, _uint_) ) val )

Transforms val to the related typed string.
Returns a mutable reference to a created string that contains the text of the integer with a default formatting.
Default formatting compacts the integer string as much as possible. Integer values are always transformed in their decimal forms. To formate differently an integer value into a string, use instead the format() built-in function as explained in above section 3.15.4 Formatting strings.
Example:

none my_print( ... vals ){
    print_end( '"' );
    for( ? val in vals[:-1] )
        print_end( ", ", str(val) );
    print_end( '"', str(val));
}    
my_print( 123, -0x100, 0b0001_1001 );  // prints: "123, -256, 19"

3.15.5.7 Casting floats to strings

const str operator cast str ( const _float_ val )

const str16 operator cast str16 ( const _float_ val )

Transforms val to the related typed string.
Returns a mutable reference to a created string that contains the text of the floating point value with a default formatting.
Default formatting compacts the float string as much as possible. Floating points values are always transformed in their non-engineer forms. To formate differently a floating point value into a string, use instead the format() built-in function as explained in above section 3.15.4 Formatting strings.

print( str(" 0.123456"), str("99.87E+007") );  // prints: 0.12346 9.987e8

3.15.5.8 Casting booleans to strings

str operator cast str ( const bool val )

str16 operator cast str16 ( const bool val )

Transforms boolean val to the related typed string.
Returns a mutable reference to a created string that contains the text of the boolean value with a default formatting – see example below.
Example:

print( str(True), str16(False) );  // prints: true false

3.15.5.9 Casting slices to strings

str operator cast str ( const slice slc )

str16 operator cast str16 ( const slice slc )

Not that much used, but always possible.
Transforms slc to the a mutable string with specified typed of string.
Returns a mutable reference to a created string that contains the text related to the slice with a default formatting – see example below.
Reminder: slices Typee grammar rules are:

<slice literal> ::= '[' <start> ':' [<end> [':' <step>]] ']'
<end>           ::= <integer>
<start>         ::= <integer>
<step>          ::= <integer>

Example:

str16 txt = str16( [ 1 : 0x104: 0b101 ) );  // automatically modified as const str16()
print_sep( '', '"', txt, '"' );  // prints: "[1:260:5)"

3.15.5.10 Casting classes to strings

Just define operator str and/or str16 in your class, and any of its instances will be cast-able to strings of the defined types.

Example:

class MyClass {
  :public:
    
    float32 val;
  
    MyClass(){
        me.val = 0.0;
    }
    MyClass( const float32 val ){
        me.val = val;
    }

    str operator cast str( MyClass obj )
        return str( me.val );

    str operator cast str( const MyClass obj )
        return str( me.val );
}

MyClass my_c = MyClass( 3.1415_9267 );
print( my_c );  // prints: 3.14159, with automatic casting to string

3.15.6 Conclusion

This completes the documentation on strings in Typee.

 
Next section formerly explains the Typee built-in containers.

< previous (3.14 embedding code) | (4. built-in containers) next >