Strings and Characters
IsChar and IsString
type
doublequotes
singlequotes
<#Include Label="IsChar"> <#Include Label="IsString">

Strings As Lists

Note that a string is just a special case of a list. So everything that is possible for lists (see ) is also possible for strings. Thus you can access the characters in such a string (see ), test for membership (see ), ask for the length, concatenate strings (see ), form substrings etc. You can even assign to a mutable string (see ). Of course unless you assign a character in such a way that the list stays dense, the resulting list will no longer be a string.

gap> Length( s2 ); 12 gap> s2[2]; 'e' gap> 'a' in s2; false gap> s2[2] := 'a';; s2; "Hallo world." gap> s1{ [1..4] }; "Hell" gap> Concatenation( s1{ [ 1 .. 6 ] }, s1{ [ 1 .. 4 ] } ); "Hello Hell"
Printing Strings
If a string is displayed by , for example as result of an evaluation (see ), or by and , it is displayed with enclosing doublequotes. (But note that there is an ambiguity for the empty string which is also an empty list of arbitrary &GAP; objects; it is only printed like a string if it was input as empty string or converted to a string with .) The output of can be read back into &GAP;.

Strings behave differently from other &GAP; objects with respect to , , or . These commands interpret a string in the sense that they essentially send the characters of the string directly to the output stream/file. (But depending on the type of the stream and the presence of some special characters used as hints for line breaks there may be sent some additional newline (or backslash and newline) characters.

gap> s4:= "abc\"def\nghi";; gap> View( s4 ); Print( "\n" ); "abc\"def\nghi" gap> ViewObj( s4 ); Print( "\n" ); "abc\"def\nghi" gap> PrintObj( s4 ); Print( "\n" ); "abc\"def\nghi" gap> Print( s4 ); Print( "\n" ); abc"def ghi gap> s := "German uses strange characters: äöüß\n"; "German uses strange characters: äöüß\n" gap> Print(s); German uses strange characters: äöüß gap> PrintObj(s); Print( "\n" ); "German uses strange characters: \303\244\303\266\303\274\303\237\n"

gap> s := "\007"; "\007" gap> Print(s); # rings bell in many terminals

Note that only those line breaks are printed by that are contained in the string (\n characters, see ), as is shown in the example below.

gap> s1; "Hello world." gap> Print( s1 ); Hello world.gap> Print( s1, "\n" ); Hello world. gap> Print( s1, "\nnext line\n" ); Hello world. next line
Special Characters
escaped characters
special character sequences

There are a number of special character sequences that can be used between the singlequotes of a character literal or between the doublequotes of a string literal to specify characters. They consist of two characters. The first is a backslash \. The second may be any character. If it is an octal digit (from 0 to 7) there must be two more such digits. The meaning is given in the following list

\n
newline character
. This is the character that, at least on UNIX systems, separates lines in a text file. Printing of this character in a string has the effect of moving the cursor down one line and back to the beginning of the line.
\"
doublequote character
\"
doublequote character
. Inside a string a doublequote must be escaped by the backslash, because it is otherwise interpreted as end of the string.
\'
singlequote character
\'
singlequote character
. Inside a character a singlequote must escaped by the backslash, because it is otherwise interpreted as end of the character.
\\
backslash character
\\
backslash character
. Inside a string a backslash must be escaped by another backslash, because it is otherwise interpreted as first character of an escape sequence.
\b
backspace character
\b
backspace character
. Printing this character should have the effect of moving the cursor back one character. Whether it works or not is system dependent and should not be relied upon.
\r
carriage return character
\r
carriage return character
. Printing this character should have the effect of moving the cursor back to the beginning of the same line. Whether this works or not is again system dependent.
\c
flush character
\c
flush character
. This character is not printed. Its purpose is to flush the output queue. Usually &GAP; waits until it sees a newline before it prints a string. If you want to display a string that does not include this character use \c.
\XYZ
octal character codes
\XYZ
with X, Y, Z three octal digits. This is translated to the character corresponding to the number X * 64 + Y * 8 + Z modulo 256. This can be used to specify and store arbitrary binary data as a string in &GAP;.
escaping non-special characters
other
For any other character the backslash is simply ignored.

Again, if the line is displayed as result of an evaluation, those escape sequences are displayed in the same way that they are input.

Only , , or send the characters directly to the output stream.

gap> "This is one line.\nThis is another line.\n"; "This is one line.\nThis is another line.\n" gap> Print( last ); This is one line. This is another line.

Note in particular that it is not allowed to enclose a newline inside the string. You can use the special character sequence \n to write strings that include newline characters. If, however, an input string is too long to fit on a single line it is possible to continue it over several lines. In this case the last character of each input line, except the last line must be a backslash. Both backslash and newline are thrown away by &GAP; while reading the string. Note that the same continuation mechanism is available for identifiers and integers, see .

Internally Represented Strings
convert
<#Include Label="IsStringRep"> <#Include Label="ConvertToStringRep"> <#Include Label="CopyToStringRep"> <#Include Label="IsEmptyString">

a string
nothing
The function returns an empty string in internal representation which has enough memory allocated for len characters. This can be useful for creating and filling a string with a known number of entries.

The function gives back to &GAP;s memory manager the physical memory which is allocated for the string str in internal representation but not needed by its current number of characters.

These functions are intended for saving some of &GAP;s memory in certain situations, see the explanations and the example for the analogeous functions and for plain lists.
<#Include Label="CharsFamily">

Recognizing Characters
<#Include Label="IsDigitChar"> <#Include Label="IsLowerAlphaChar"> <#Include Label="IsUpperAlphaChar"> <#Include Label="IsAlphaChar">

Comparisons of Strings
strings
strings
The equality operator = returns true if the two strings string1 and string2 are equal and false otherwise. The inequality operator <> returns true if the two strings string1 and string2 are not equal and false otherwise.

gap> "Hello world.\n" = "Hello world.\n"; true gap> "Hello World.\n" = "Hello world.\n"; # comparison is case sensitive false gap> "Hello world." = "Hello world.\n"; # first string has no <newline> false gap> "Goodbye world.\n" = "Hello world.\n"; false gap> [ 'a', 'b' ] = "ab"; true
strings
The ordering of strings is lexicographically according to the order implied by the underlying, system dependent, character set.

gap> "Hello world.\n" < "Hello world.\n"; # the strings are equal false gap> # in ASCII capitals range before small letters: gap> "Hello World." < "Hello world."; true gap> "Hello world." < "Hello world.\n"; # prefixes are always smaller true gap> # G comes before H, in ASCII at least: gap> "Goodbye world.\n" < "Hello world.\n"; true

Strings can be compared via < with certain &GAP; objects that are not strings, see for the details.
Operations to Produce or Manipulate Strings

For the possibility to print &GAP; objects to strings, see .

<#Include Label="DisplayString">

This is the default value for .
<#Include Label="ViewString">

This is the default value for .
<#Include Label="PrintString"> <#Include Label="String">

<#Include Label="StripLineBreakCharacters">

returns a string which represents the integer int with hexa-decimal digits (using A to F as digits 10 to 15). The inverse translation can be achieved with .
<#Include Label="StringPP"> <#Include Label="WordAlp"> <#Include Label="LowercaseString"> <#Include Label="SplitString"> <#Include Label="ReplacedString">

This function changes the string string in place. The characters (space), \n, \r and \t are considered as white space. Leading and trailing white space characters in string are removed. Sequences of white space characters between other characters are replaced by a single space character.

See for a non-destructive version. gap> s := " x y \n\n\t\r z\n \n"; " x y \n\n\t\r z\n \n" gap> NormalizeWhitespace(s); gap> s; "x y z"
<#Include Label="NormalizedWhitespace">

Both arguments must be strings. This function efficiently removes all characters given in chars from string. gap> s := "ab c\ndef\n\ng h i .\n"; "ab c\ndef\n\ng h i .\n" gap> RemoveCharacters(s, " \n\t\r"); # remove all whitespace characters gap> s; "abcdefghi."
<#Include Label="JoinStringsWithSeparator"> <#Include Label="Chomp">

The following two functions convert basic strings to lists of numbers and vice versa. They are useful for examples of text encryption. <#Include Label="NumbersString"> <#Include Label="StringNumbers">

Character Conversion

The following functions convert characters in their internal integer values and vice versa. Note that the number corresponding to a particular character might depend on the system used. While most systems use an extension of ASCII, in particular character values outside the range [ 32 .. 126 ] might differ between architectures.

returns an integer value in the range [ 0 .. 255 ] that corresponds to char.
returns a character that corresponds to the integer value int, which must be in the range [ 0 .. 255 ].

gap> c:=CharInt(65); 'A' gap> IntChar(c); 65
returns a signed integer value in the range [ -128 .. 127 ] that corresponds to char.
returns a character which corresponds to the signed integer value int, which must be in the range [ -128 .. 127 ].

The signed and unsigned integer functions behave the same for values in the range [ 0 .. 127 ].

gap> SIntChar(c); 65 gap> c:=CharSInt(-20);; gap> SIntChar(c); -20 gap> IntChar(c); 236 gap> SIntChar(CharInt(255)); -1
Operations to Evaluate Strings
evaluation
return either an integer ( and ), or a rational () as represented by the string str. returns fail if non-digit characters occur in str. For , the argument string may start with the sign character -, followed by either a sequence of digits or by two sequences of digits that are separated by one of the characters / or ., where the latter stands for a decimal dot. (The methods only evaluate numbers but do not perform arithmetic!)

evaluates an integer written with hexa-decimal digits. Here the letters a-f or A-F are used as digits 10 to 15. An error occurs when a wrong character is found in the string. This function can be used (together with ) for efficiently storing and reading large integers from respectively into &GAP;. Note that the translation between integers and their hexa-decimal representation costs linear computation time in terms of the number of digits, while translation from and into decimal representation needs substantial computations. If str is not in compact string representation then is applied to it as side effect.

gap> Int("12345")+1; 12346 gap> Int("123/45"); fail gap> Int("1+2"); fail gap> Int("-12"); -12 gap> Rat("123/45"); 41/15 gap> Rat( "123.45" ); 2469/20 gap> IntHexString("-abcdef0123456789"); -12379813738877118345 gap> HexStringInt(last); "-ABCDEF0123456789"
<#Include Label="Ordinal"> <#Include Label="EvalString"> <#Include Label="CrcString">

Calendar Arithmetic
<#Include Label="[2]{string}"> <#Include Label="DaysInYear"> <#Include Label="DaysInMonth"> <#Include Label="DMYDay"> <#Include Label="DayDMY"> <#Include Label="WeekDay"> <#Include Label="StringDate"> <#Include Label="HMSMSec"> <#Include Label="SecHMSM"> <#Include Label="StringTime"> <#Include Label="SecondsDMYhms"> <#Include Label="DMYhmsSeconds">

Obtaining LaTeX Representations of Objects
LaTeX

For the purpose of generating &LaTeX; source code with &GAP; it is recommended to add new functions which will print the &LaTeX; source or return &LaTeX; strings for further processing.

An alternative approach could be based on methods for the default &LaTeX; representation for each appropriate type of objects. However, there is no clear notion of a default &LaTeX; code for any non-trivial mathematical object; moreover, different output may be required in different contexts.

While customisation of such an operation may require changes in a variety of methods that may be distributed all over the library, the user will have a clean overview of the whole process of &LaTeX; code generation if it is contained in a single function. Furthermore, there may be kinds of objects which are not detected by the method selection, or there may be a need in additional parameters specifying requirements for the output.

This is why having a special purpose function for each particular case is more suitable. &GAP; provides several functions that produce &LaTeX; strings for those situations where this is nontrivial and reasonable. A useful example is from the &GAP; library, others can be found entering ?LaTeX at the &GAP; prompt. Package authors are encouraged to add an index entry LaTeX to the documentation of all &LaTeX; string producing functions. This way, entering ?LaTeX will give an overview of all documented functionality in this direction.