27 Strings and Characters
  
  
  27.1 IsChar and IsString
  
  27.1-1 IsChar
  
  IsChar( obj )  Category
  IsCharCollection( obj )  Category
  
  A  character  is  simply  an  object  in  GAP  that  represents an arbitrary
  character from the character set of the operating system. Character literals
  can be entered in GAP by enclosing the character in singlequotes '.
  
    Example  
    gap> x:= 'a';  IsChar( x );
    'a'
    true
    gap> '*';
    '*'
  
  
  27.1-2 IsString
  
  IsString( obj )  filter
  
  A  string  is  a  dense  list (see IsList (21.1-1), IsDenseList (21.1-2)) of
  characters  (see IsChar  (27.1-1));  thus  strings  are  always  homogeneous
  (see IsHomogeneousList (21.1-3)).
  
  A  string  literal  can  either  be  entered as the list of characters or by
  writing  the  characters  between  doublequotes  ".  GAP  will always output
  strings in the latter format. However, the input via the double quote syntax
  enables   GAP   to  store  the  string  in  an  efficient  compact  internal
  representation. See IsStringRep (27.4-1) below for more details.
  
  Each  character, in particular those which cannot be typed directly from the
  keyboard,  can  also  be  typed  in three digit octal notation, or two digit
  hexadecimal  notation.  And  for  some  special characters (like the newline
  character) there is a further possibility to type them, see section 27.2.
  
    Example  
    gap> s1 := ['H','e','l','l','o',' ','w','o','r','l','d','.'];
    "Hello world."
    gap> IsString( s1 );
    true
    gap> s2 := "Hello world.";
    "Hello world."
    gap> s1 = s2;
    true
    gap> s3 := "";  # the empty string
    ""
    gap> s3 = [];
    true
    gap> IsString( [] );
    true
    gap> IsString( "123" );  IsString( 123 );
    true
    false
    gap> IsString( [ '1', '2', '3' ] );
    true
    gap> IsString( [ '1', '2', , '4' ] );  # strings must be dense
    false
    gap> IsString( [ '1', '2', 3 ] );  # strings must only contain characters
    false
  
  
  
  27.1-3 Strings As Lists
  
  Note  that  a string is just a special case of a list. So everything that is
  possible  for  lists  (see 21)  is  also  possible for strings. Thus you can
  access  the  characters  in  such  a  string (see 21.3), test for membership
  (see 30.6),  ask  for  the  length,  concatenate  strings (see Concatenation
  (21.20-1)),  form  substrings  etc.  You can even assign to a mutable string
  (see 21.4).  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.
  
    Example  
    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"
  
  
  
  27.1-4 Printing Strings
  
  ViewObj( str )  method
  PrintObj( str )  method
  
  If  a  string  is  displayed  by  View  (6.3-3), for example as result of an
  evaluation  (see 6.1),  or  by  ViewObj  (6.3-5) and PrintObj (6.3-5), 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  ConvertToStringRep  (27.4-2).) The output of
  PrintObj can be read back into GAP.
  
  Strings  behave  differently  from  other  GAP objects with respect to Print
  (6.3-4),  PrintTo  (9.7-3),  or AppendTo (9.7-3). 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.
  
    Example  
    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"
  
  
    Example  
    gap> s := "\007";
    "\007"
    gap> Print(s); # rings bell in many terminals
  
  
  Note  that  only  those  line  breaks  are printed by Print (6.3-4) that are
  contained  in  the  string  (\n  characters,  see 27.2),  as is shown in the
  example below.
  
    Example  
    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
  
  
  
  27.2 Special Characters
  
  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 a backslash \ followed
  by a second character indicating the type of special character sequence, and
  possibly  more  characters.  The  following  special character sequences are
  currently  defined.  For  any  other sequence starting with a backslash, the
  backslash is ignored.
  
   \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.  Inside a string a doublequote must be escaped
        by  the  backslash,  because it is otherwise interpreted as end of the
        string.
  
   \'
        singlequote  character.  Inside a character a singlequote must escaped
        by  the  backslash,  because it is otherwise interpreted as end of the
        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. 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.  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.  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
        with  X,  Y,  Z three octal digits, that is one of "01234567". 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.
  
   \0xYZ
        with    Y,    and    Z    hexadecimal   digits,   that   is   one   of
        "0123456789ABCDEFabcdef",  where  a to f and A to F are interpreted as
        the   numbers   10   to  15.  This  is  translated  to  the  character
        corresponding to the number Y*16 + Z.
  
   other
        For any other character the backslash is 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 Print (6.3-4), PrintTo (9.7-3), or AppendTo (9.7-3) send the characters
  directly to the output stream.
  
    Example  
    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 6.2. The rules on escaping are ignored in a
  triple quoted string, see 27.3
  
  
  27.3 Triple Quoted Strings
  
  Another  method  of entering strings in GAP is triple quoted strings. Triple
  quoted  strings  ignore  the  rules on escaping given in 27.2. Triple quoted
  strings  begin  an  end with three doublequotes. Inside the triple quotes no
  escaping  is done, and the string continues, including newlines, until three
  doublequotes are found.
  
    Example  
    gap> """Print("\n")""";
    "Print(\"\\n\")"
  
  
  Triple  quoted  strings  are represented internally identically to all other
  strings,  they  only provide an alternative method of giving strings to GAP.
  Triple  quoted  strings  still  follow GAP's line editing rules (6.2), which
  state  that  in  normal line editing mode, lines starting gap> , >  or brk> 
  will have this beginning part removed.
  
  
  27.4 Internally Represented Strings
  
  27.4-1 IsStringRep
  
  IsStringRep( obj )  Representation
  
  IsStringRep  is  a  special  (internal)  representation  of  dense  lists of
  characters.   Dense   lists   of  characters  can  be  converted  into  this
  representation using ConvertToStringRep (27.4-2). Note that calling IsString
  (27.1-2) does not change the representation.
  
  27.4-2 ConvertToStringRep
  
  ConvertToStringRep( obj )  function
  
  If   obj   is  a  dense  internally  represented  list  of  characters  then
  ConvertToStringRep  changes the representation to IsStringRep (27.4-1). This
  is  useful  in particular for converting the empty list [], which usually is
  in  IsPlistRep  (21.24-2),  to  IsStringRep (27.4-1). If obj is not a string
  then ConvertToStringRep signals an error.
  
  27.4-3 CopyToStringRep
  
  CopyToStringRep( obj )  function
  
  If   obj   is  a  dense  internally  represented  list  of  characters  then
  CopyToStringRep  copies  obj to a new object with representation IsStringRep
  (27.4-1). If obj is not a string then CopyToStringRep signals an error.
  
  27.4-4 IsEmptyString
  
  IsEmptyString( str )  function
  
  IsEmptyString  returns true if str is the empty string in the representation
  IsStringRep  (27.4-1),  and false otherwise. Note that the empty list [] and
  the  empty  string "" have the same type, the recommended way to distinguish
  them  is  via  IsEmptyString.  For  formatted  printing, this distinction is
  sometimes necessary.
  
    Example  
    gap> l:= [];;  IsString( l );  IsEmptyString( l );  IsEmpty( l );
    true
    false
    true
    gap> l;  ConvertToStringRep( l );  l;
    [  ]
    ""
    gap> IsEmptyString( l );  IsEmptyString( "" );  IsEmptyString( "abc" );
    true
    true
    false
    gap> ll:= [ 'a', 'b' ];  IsStringRep( ll );  ConvertToStringRep( ll );
    "ab"
    false
    gap> ll;  IsStringRep( ll );
    "ab"
    true
  
  
  27.4-5 EmptyString
  
  EmptyString( len )  function
  Returns:  a string
  
  ShrinkAllocationString( str )  function
  Returns:  nothing
  
  The  function EmptyString 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  ShrinkAllocationString  gives back to GAPs 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 GAPs memory in certain
  situations,  see  the  explanations  and  the  example  for  the  analogeous
  functions  EmptyPlist  (21.9-1) and ShrinkAllocationPlist (21.9-1) for plain
  lists.
  
  27.4-6 CharsFamily
  
  CharsFamily  family
  
  Each  character lies in the family CharsFamily, each nonempty string lies in
  the  collections  family of this family. Note the subtle differences between
  the empty list [] and the empty string "" when both are printed.
  
  
  27.5 Recognizing Characters
  
  27.5-1 IsDigitChar
  
  IsDigitChar( c )  function
  
  checks  whether  the  character  c  is  a  digit, i.e., occurs in the string
  "0123456789".
  
  27.5-2 IsLowerAlphaChar
  
  IsLowerAlphaChar( c )  function
  
  checks  whether the character c is a lowercase alphabet letter, i.e., occurs
  in the string "abcdefghijklmnopqrstuvwxyz".
  
  27.5-3 IsUpperAlphaChar
  
  IsUpperAlphaChar( c )  function
  
  checks whether the character c is an uppercase alphabet letter, i.e., occurs
  in the string "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
  
  27.5-4 IsAlphaChar
  
  IsAlphaChar( c )  function
  
  checks  whether  the  character  c  is  either  a  lowercase or an uppercase
  alphabet letter.
  
  
  27.6 Comparisons of Strings
  
  27.6-1 \=
  
  \=( string1, string2 )  method
  
  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.
  
    Example  
    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
  
  
  27.6-2 \<
  
  \<( string1, string2 )  method
  
  The  ordering of strings is lexicographically according to the order implied
  by the underlying, system dependent, character set.
  
    Example  
    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 4.13 for the details.
  
  
  27.7 Operations to Produce or Manipulate Strings
  
  For the possibility to print GAP objects to strings, see 10.7.
  
  27.7-1 DisplayString
  
  DisplayString( obj )  operation
  
  Returns  a  string  which could be used to display the object obj in a nice,
  formatted  way which is easy to read (but might be difficult for machines to
  understand).  The  actual  format  used for this depends on the type of obj.
  Each  method should include a newline character as last character. Note that
  no  method  for  DisplayString may delegate to any of the operations Display
  (6.3-6), ViewObj (6.3-5) or PrintObj (6.3-5) to avoid circular delegations.
  
  27.7-2 DEFAULTDISPLAYSTRING
  
  DEFAULTDISPLAYSTRING  global variable
  
  This is the default value for DisplayString (27.7-1).
  
  27.7-3 ViewString
  
  ViewString( obj )  operation
  
  ViewString  returns a string which would be displayed by ViewObj (6.3-5) for
  an  object.  Note  that  no method for ViewString may delegate to any of the
  operations  Display  (6.3-6),  ViewObj  (6.3-5),  DisplayString  (27.7-1) or
  PrintObj (6.3-5) to avoid circular delegations.
  
  27.7-4 DEFAULTVIEWSTRING
  
  DEFAULTVIEWSTRING  global variable
  
  This is the default value for ViewString (27.7-3).
  
  27.7-5 PrintString
  
  PrintString( obj[, length] )  operation
  
  PrintString  returns  a  representation  of  obj,  which may be an object of
  arbitrary  type,  as  a string. This string should approximate as closely as
  possible  the  character  sequence  you  see if you print obj using PrintObj
  (6.3-5).
  
  If  length  is  given  it  must  be an integer. The absolute value gives the
  minimal length of the result. If the string representation of obj takes less
  than that many characters it is filled with blanks. If length is positive it
  is filled on the left, if length is negative it is filled on the right.
  
  In  the  two  argument case, the string returned is a new mutable string (in
  particular  not  a part of any other object); it can be modified safely, and
  MakeImmutable (12.6-4) may be safely applied to it.
  
    Example  
    gap> PrintString(123);PrintString([1,2,3]);
    "123"
    "[ 1, 2, 3 ]"
  
  
  PrintString is entitled to put in additional control characters \< (ASCII 1)
  and \> (ASCII 2) that allow proper line breaks. See StripLineBreakCharacters
  (27.7-7) for a function to get rid of these control characters.
  
  27.7-6 String
  
  String( obj[, length] )  attribute
  
  String  returns a representation of obj, which may be an object of arbitrary
  type, as a string. This string should approximate as closely as possible the
  character sequence you see if you print obj.
  
  If  length  is  given  it  must  be an integer. The absolute value gives the
  minimal length of the result. If the string representation of obj takes less
  than that many characters it is filled with blanks. If length is positive it
  is filled on the left, if length is negative it is filled on the right.
  
  In  the  two  argument case, the string returned is a new mutable string (in
  particular  not  a part of any other object); it can be modified safely, and
  MakeImmutable (12.6-4) may be safely applied to it.
  
    Example  
    gap> String(123);String([1,2,3]);
    "123"
    "[ 1, 2, 3 ]"
  
  
  String  must  not  put  in additional control characters \< (ASCII 1) and \>
  (ASCII 2) that allow proper line breaks.
  
  27.7-7 StripLineBreakCharacters
  
  StripLineBreakCharacters( st )  function
  
  This  function  takes  a  string  st  as an argument and removes all control
  characters  \<  (ASCII  1)  and  \>  (ASCII 2) which are used by PrintString
  (27.7-5)  and  PrintObj (6.3-5) to ensure proper line breaking. A new string
  with these characters removed is returned.
  
  27.7-8 HexStringInt
  
  HexStringInt( int )  function
  
  returns  a  string  which represents the integer int with hexadecimal digits
  (using  A  to F as digits 10 to 15). The inverse translation can be achieved
  with IntHexString (27.9-3).
  
  27.7-9 StringPP
  
  StringPP( int )  function
  
  returns  a string representing the prime factor decomposition of the integer
  int. See also PrintFactorsInt (14.4-10).
  
    Example  
    gap> StringPP(40320);
    "2^7*3^2*5*7"
  
  
  27.7-10 WordAlp
  
  WordAlp( alpha, nr )  function
  
  returns a string that is the nr-th word over the alphabet list alpha, w.r.t.
  word  length  and lexicographical order. The empty word is WordAlp( alpha, 0
  ).
  
    Example  
    gap> List([0..5],i->WordAlp("abc",i));
    [ "", "a", "b", "c", "aa", "ab" ]
  
  
  27.7-11 LowercaseString
  
  LowercaseString( string )  function
  
  Returns a lowercase version of the string string, that is, a string in which
  each uppercase alphabet character is replaced by the corresponding lowercase
  character.
  
    Example  
    gap> LowercaseString("This Is UpperCase");
    "this is uppercase"
  
  
  27.7-12 LowercaseChar
  
  LowercaseChar( character )  function
  
  Returns the lowercase version of the character character.
  
  27.7-13 UppercaseString
  
  UppercaseString( string )  function
  
  Returns a uppercase version of the string string, that is, a string in which
  each lowercase alphabet character is replaced by the corresponding uppercase
  character.
  
    Example  
    gap> UppercaseString("This Is UpperCase");
    "THIS IS UPPERCASE"
  
  
  27.7-14 UppercaseChar
  
  UppercaseChar( character )  function
  
  Returns the uppercase version of the character character.
  
  27.7-15 SplitString
  
  SplitString( string, seps[, wspace] )  operation
  
  This function accepts a string string and lists seps and, optionally, wspace
  of  characters.  Now string is split into substrings at each occurrence of a
  character  in  seps  or  wspace. The characters in wspace are interpreted as
  white  space  characters.  Substrings of characters in wspace are treated as
  one white space character and they are ignored at the beginning and end of a
  string.
  
  Both arguments seps and wspace can be single characters.
  
  Each  string  in  the  resulting  list  of  substring  does  not contain any
  characters in seps or wspace.
  
  A  character that occurs both in seps and wspace is treated as a white space
  character.
  
  A  separator  at the end of a string is interpreted as a terminator; in this
  case, the separator does not produce a trailing empty string. Also see Chomp
  (27.7-21).
  
    Example  
    gap> SplitString( "substr1:substr2::substr4", ":" );
    [ "substr1", "substr2", "", "substr4" ]
    gap> SplitString( "a;b;c;d;", ";" );
    [ "a", "b", "c", "d" ]
    gap> SplitString( "/home//user//dir/", "", "/" );
    [ "home", "user", "dir" ]
  
  
  27.7-16 ReplacedString
  
  ReplacedString( string, old, new )  function
  
  replaces  occurrences  of the string old in string by new, starting from the
  left and always replacing the first occurrence. To avoid infinite recursion,
  characters  which  have  been  replaced  already, are not subject to renewed
  replacement.
  
    Example  
    gap> ReplacedString("abacab","a","zl");
    "zlbzlczlb"
    gap> ReplacedString("ababa", "aba","c");
    "cba"
    gap> ReplacedString("abacab","a","ba");
    "babbacbab"
  
  
  27.7-17 NormalizeWhitespace
  
  NormalizeWhitespace( string )  function
  
  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 NormalizedWhitespace (27.7-18) for a non-destructive version.
  
    Example  
    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"
  
  
  27.7-18 NormalizedWhitespace
  
  NormalizedWhitespace( str )  function
  
  This  function  returns  a  copy  of string str to which NormalizeWhitespace
  (27.7-17) was applied.
  
  27.7-19 RemoveCharacters
  
  RemoveCharacters( string, chars )  function
  
  Both  arguments  must  be  strings.  This  function  efficiently removes all
  characters given in chars from string.
  
    Example  
    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."
  
  
  27.7-20 JoinStringsWithSeparator
  
  JoinStringsWithSeparator( list[, sep] )  function
  
  joins list (a list of strings) after interpolating sep (or "," if the second
  argument  is omitted) between each adjacent pair of strings; sep should be a
  string.
  
    Example  
    gap> list := List([1..10], String);
    [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10" ]
    gap> JoinStringsWithSeparator(list);
    "1,2,3,4,5,6,7,8,9,10"
    gap> JoinStringsWithSeparator(["The", "quick", "brown", "fox"], " ");
    "The quick brown fox"
    gap> new:= JoinStringsWithSeparator(["a", "b", "c", "d"], ",\n    ");
    "a,\n    b,\n    c,\n    d"
    gap> Print("    ", new, "\n");
        a,
        b,
        c,
        d
  
  
  27.7-21 Chomp
  
  Chomp( str )  function
  
  Like  the  similarly  named  Perl function, Chomp removes a trailing newline
  character  (or carriage-return line-feed couplet) from a string argument str
  if  present  and returns the result. If str is not a string or does not have
  such  trailing  character(s)  it is returned unchanged. This latter property
  means  that  Chomp  is  safe  to  use in cases where one is manipulating the
  result of another function which might sometimes return fail.
  
    Example  
    gap> Chomp("The quick brown fox jumps over the lazy dog.\n");
    "The quick brown fox jumps over the lazy dog."
    gap> Chomp("The quick brown fox jumps over the lazy dog.\r\n");
    "The quick brown fox jumps over the lazy dog."
    gap> Chomp("The quick brown fox jumps over the lazy dog.");
    "The quick brown fox jumps over the lazy dog."
    gap> Chomp(fail);
    fail
    gap> Chomp(32);
    32
  
  
  Note:  Chomp  only  removes  a  trailing newline character from str. If your
  string  contains several newline characters and you really want to split str
  into  lines  at the newline characters (and remove those newline characters)
  then you should use SplitString (27.7-15), e.g.
  
    Example  
    gap> str := "The quick brown fox\njumps over the lazy dog.\n";
    "The quick brown fox\njumps over the lazy dog.\n"
    gap> SplitString(str, "", "\n");
    [ "The quick brown fox", "jumps over the lazy dog." ]
    gap> Chomp(str);
    "The quick brown fox\njumps over the lazy dog."
  
  
  27.7-22 StartsWith
  
  StartsWith( string, prefix )  function
  EndsWith( string, suffix )  function
  
  Determines whether a string starts or ends with another string.
  
  27.7-23 StringFormatted
  
  StringFormatted( string, data... )  function
  PrintFormatted( string, data... )  function
  PrintToFormatted( stream, string, data... )  function
  
  These  functions perform a string formatting operation. They accept a format
  string,  which  can contain replacement fields which are delimited by braces
  {}.  Each  replacement  field  contains  a  numeric  or positional argument,
  describing the element of data to replace the braces with.
  
  There  are  three formatting functions, which differ only in how they output
  the   formatted   string.  StringFormatted  returns  the  formatted  string,
  PrintFormatted  prints the formatted string and PrintToFormatted appends the
  formatted  string  to  stream,  which  can  be  either an output stream or a
  filename.
  
  The arguments after string form a list data of values used to substitute the
  replacement fields in string, using the following formatting rules:
  
  string  is  treated  as  a normal string, except for occurrences of { and },
  which follow special rules, as follows:
  
  The  contents  of  {  }  is split by a ! into {id!format}, where both id and
  format  are  optional.  If the ! is ommitted, the bracket is treated as {id}
  with no format.
  
  id is interpreted as follows:
  
  An integer i
        Take the ith element of data.
  
  A string str
        If this is used, the first element of data must be a record r. In this
        case, the value r.(str) is taken.
  
  No id given
        Take  the  jth  element  of data, where j is the number of replacement
        fields  with  no  id  in  the format string so far. If any replacement
        field has no id, then all replacement fields must have no id.
  
  A  single  brace  can  be  outputted by doubling, so {{ in the format string
  produces { and }} produces }.
  
  The  format  decides  how  the  variable is printed. format must be one of s
  (which uses String (27.7-6)), v (which uses ViewString (27.7-3)) or d (which
  calls DisplayString (27.7-1)). The default value for format is s.
  
    Example  
    gap> StringFormatted("I have {} cats and {} dogs", 4, 5);
    "I have 4 cats and 5 dogs"
    gap> StringFormatted("I have {2} cats and {1} dogs", 4, 5);
    "I have 5 cats and 4 dogs"
    gap> StringFormatted("I have {cats} cats and {dogs} dogs", rec(cats:=3, dogs:=2));
    "I have 3 cats and 2 dogs"
    gap> StringFormatted("We use {{ and }} to mark {dogs} dogs", rec(cats:=3, dogs:=2));
    "We use { and } to mark 2 dogs"
    gap> sym3 := SymmetricGroup(3);;
    gap> StringFormatted("String: {1!s}, ViewString: {1!v}", sym3);
    "String: SymmetricGroup( [ 1 .. 3 ] ), ViewString: Sym( [ 1 .. 3 ] )"
  
  
  The  following  two  functions convert basic strings to lists of numbers and
  vice versa. They are useful for examples of text encryption.
  
  27.7-24 NumbersString
  
  NumbersString( s, m[, table] )  function
  
  NumbersString  takes a string message s and returns a list of integers, each
  not  exceeding  the integer m that encode the message using the scheme A=11,
  B=12  and  so  on  (and  converting  lower case to upper case). If a list of
  characters is given in table, it is used instead for encoding).
  
    Example  
    gap> l:=NumbersString("Twas brillig and the slithy toves",1000000);
    [ 303311, 291012, 281922, 221917, 101124, 141030, 181510, 292219, 
      301835, 103025, 321529 ]
  
  
  27.7-25 StringNumbers
  
  StringNumbers( l, m[, table] )  function
  
  StringNumbers   takes   a   list  l  of  integers  that  was  encoded  using
  NumbersString  (27.7-24)  and  the  size  integer  m,  and returns a message
  string,  using  the  scheme A=11, B=12 and so on. If a list of characters is
  given in table, it is used instead for decoding).
  
    Example  
    gap> StringNumbers(l,1000000);
    "TWAS BRILLIG AND THE SLITHY TOVES"
  
  
  27.7-26 StringOfMemoryAmount
  
  StringOfMemoryAmount( numbytes )  function
  
  This  function  returns  a  human-readable  string  representing numbytes of
  memory.  It  is  used  in  printing amounts of memory allocated by tests and
  benchmarks. Binary prefixes (representing powers of 1024) are used.
  
    Example  
    gap> StringOfMemoryAmount(123456789);
    "117MB"
  
  
  
  27.8 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.
  
  27.8-1 IntChar
  
  IntChar( char )  function
  
  returns an integer value in the range [ 0 .. 255 ] that corresponds to char.
  
  27.8-2 CharInt
  
  CharInt( int )  function
  
  returns a character that corresponds to the integer value int, which must be
  in the range [ 0 .. 255 ].
  
    Example  
    gap> c:=CharInt(65);
    'A'
    gap> IntChar(c);
    65
  
  
  27.8-3 SIntChar
  
  SIntChar( char )  function
  
  returns a signed integer value in the range [ -128 .. 127 ] that corresponds
  to char.
  
  27.8-4 CharSInt
  
  CharSInt( int )  function
  
  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 ].
  
    Example  
    gap> SIntChar(c);
    65
    gap> c:=CharSInt(-20);;
    gap> SIntChar(c);
    -20
    gap> IntChar(c);
    236
    gap> SIntChar(CharInt(255));
    -1
  
  
  
  27.9 Operations to Evaluate Strings
  
  27.9-1 Int
  
  Int( str )  attribute
  
  returns an integer as represented by the string str. The argument string may
  optionally  start  with  the  sign  character  -,  followed by a sequence of
  decimal digits. For any other input fail is returned.
  
  For  backwards  compatibility, the empty string is accepted, in which case 0
  is returned as result.
  
    Example  
    gap> Int("12345");
    12345
    gap> Int("123/45");
    fail
    gap> Int("1+2");
    fail
    gap> Int("-12");
    -12
    gap> Int("");
    0
  
  
  27.9-2 Rat
  
  Rat( str )  attribute
  
  returns a rational as represented by the string str. The argument string may
  optionally start with the sign character -, followed by either a sequence of
  decimal  digits  or by two sequences of decimal digits that are separated by
  one of the characters / or ., where the latter stands for a decimal dot. For
  any other input fail is returned.
  
    Example  
    gap> Rat("123/45");
    41/15
    gap> Rat("-123.45");
    -2469/20
  
  
  27.9-3 IntHexString
  
  IntHexString( str )  function
  
  returns an integer as represented by the string str. The argument string may
  optionally  start  with  the  sign  character  -,  followed by a sequence of
  hexadecimal digits. Here the letters a-f or A-F are used as digits 10 to 15.
  Any other input results in an error.
  
  This  function  can  be  used  (together  with  HexStringInt  (27.7-8))  for
  efficiently  storing  and reading large integers from respectively into GAP.
  Note   that   the   translation   between  integers  and  their  hexadecimal
  representation  costs  linear  computation  time  in  terms of the number of
  digits,  while  translation  from  and  into  decimal  representation  needs
  substantial computations.
  
    Example  
    gap> IntHexString("-abcdef0123456789");
    -12379813738877118345
    gap> HexStringInt(last);
    "-ABCDEF0123456789"
  
  
  27.9-4 Ordinal
  
  Ordinal( n )  function
  
  returns the ordinal of the integer n as a string.
  
    Example  
    gap> Ordinal(2);  Ordinal(21);  Ordinal(33);  Ordinal(-33);
    "2nd"
    "21st"
    "33rd"
    "-33rd"
  
  
  27.9-5 EvalString
  
  EvalString( expr )  function
  
  passes  the  string expr through an input text stream so that GAP interprets
  it, and returns the result.
  
    Example  
    gap> a:=10;
    10
    gap> EvalString("a^2");
    100
  
  
  EvalString is intended for single expressions. A sequence of commands may be
  interpreted   by   using   the   functions   InputTextString   (10.7-1)  and
  ReadAsFunction (10.3-2) together; see 10.3 for an example.
  
  If  EvalString  is  used  inside  a function, then it doesn't know about the
  local  variables and the arguments of the function. A possible workaround is
  to  define global variables in advance, and then to assign the values of the
  local variables to the global ones, like in the example below.
  
    Example  
    gap> global_a := 0;;
    gap> global_b := 0;;
    gap> example := function ( local_a )
    >     local  local_b;
    >     local_b := 5;
    >     global_a := local_a;
    >     global_b := local_b;
    >     return EvalString( "global_a * global_b" );
    > end;;
    gap> example( 2 );
    10
  
  
  27.9-6 CrcString
  
  CrcString( str )  function
  Returns:  an integer
  
  This  function computes a CRC (cyclic redundancy check) number from a string
  str. See also CrcFile (9.7-7) and HexSHA256 (27.9-7).
  
    Example  
    gap> CrcString("GAP example string");
    -50451670
  
  
  27.9-7 HexSHA256
  
  HexSHA256( string )  function
  HexSHA256( stream )  function
  
  Return  the  SHA-256 cryptographic checksum of the bytes in string, resp. of
  the  data  in  the input stream object stream (see Chapter 10 to learn about
  streams) when read from the current position until EOF (end-of-file).
  
  The checksum is returned as string with 64 lowercase hexadecimal digits.
  
    Example  
    gap> HexSHA256("abcd");
    "88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
    gap> HexSHA256(InputTextString("abcd"));
    "88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
  
  
  27.9-8 Pluralize
  
  Pluralize( [count, ]string[, plural] )  function
  Returns:  A string
  
  This  function  returns  an  attempt  at  the appropriate pluralization of a
  string  (considered  as  a  singular  English noun), using several rules and
  heuristics of English grammar.
  
  The  arguments  to  this function are an optional non-negative integer count
  (the number of objects in question), a non-empty string string (the singular
  form  of  the  object in question), and an optional additional string plural
  (the plural form of string).
  
  If  plural  is  given,  then Pluralize uses it as the plural form of string,
  otherwise Pluralize makes an informed guess at the plural.
  
  If count is not given, then Pluralize returns this plural form of string. If
  count  is given and has value n ≠ 1, then this string is prepended by "\>n\<
  ";  else  if  count has value 1, then Pluralize returns string, prepended by
  "\>1\< ".
  
  Note  that  StripLineBreakCharacters  (27.7-7)  can  be  used  to remove the
  control characters \< and \> from the return value.
  
    Example  
    gap> Pluralize( "generator" );
    "generators"
    gap> Pluralize( 1, "generator" );
    "\>1\< generator"
    gap> Pluralize( 0, "generator" );
    "\>0\< generators"
    gap> Pluralize( "man", "men" );
    "men"
    gap> Pluralize( 1, "man", "men" );
    "\>1\< man"
    gap> Print( Pluralize( 2, "man", "men" ) );
    2 men
    gap> Print( Pluralize( 2, "vertex" ) );
    2 vertices
    gap> Print( Pluralize( 3, "matrix" ) );
    3 matrices
    gap> Print( Pluralize( 4, "battery" ) );
    4 batteries
  
  
  
  27.10 Calendar Arithmetic
  
  All calendar functions use the Gregorian calendar.
  
  27.10-1 DaysInYear
  
  DaysInYear( year )  function
  
  returns the number of days in the year year.
  
  27.10-2 DaysInMonth
  
  DaysInMonth( month, year )  function
  
  returns  the number of days in month number month of year, and fail if month
  is not in the valid range.
  
    Example  
    gap> DaysInYear(1998);
    365
    gap> DaysInMonth(3,1998);
    31
  
  
  27.10-3 DMYDay
  
  DMYDay( day )  function
  
  converts a number of days, starting 1-Jan-1970, to a list [ day, month, year
  ] in Gregorian calendar counting.
  
  27.10-4 DayDMY
  
  DayDMY( dmy )  function
  
  returns  the  number of days from 01-Jan-1970 to the day given by dmy, which
  must  be  a  list  of  the  form  [ day, month, year ] in Gregorian calendar
  counting. The result is fail on input outside valid ranges.
  
  Note  that  this  makes not much sense for early dates like: before 1582 (no
  Gregorian  calendar  at  all),  or  before  1753  in  many  English speaking
  countries or before 1917 in Russia.
  
  27.10-5 WeekDay
  
  WeekDay( date )  function
  
  returns  the  weekday  of a day given by date, which can be a number of days
  since 1-Jan-1970 or a list [ day, month, year ].
  
  27.10-6 StringDate
  
  StringDate( date )  function
  
  converts  date  to  a  readable  string.  date can be a number of days since
  1-Jan-1970 or a list [ day, month, year ].
  
    Example  
    gap> DayDMY([1,1,1970]);DayDMY([2,1,1970]);
    0
    1
    gap> DMYDay(12345);
    [ 20, 10, 2003 ]
    gap> WeekDay([11,3,1998]);
    "Wed"
    gap> StringDate([11,3,1998]);
    "11-Mar-1998"
  
  
  27.10-7 HMSMSec
  
  HMSMSec( msec )  function
  
  converts  a  number msec of milliseconds into a list [ hour, min, sec, milli
  ].
  
  27.10-8 SecHMSM
  
  SecHMSM( hmsm )  function
  
  is the reverse of HMSMSec (27.10-7).
  
  27.10-9 StringTime
  
  StringTime( time )  function
  
  converts time (given as a number of milliseconds or a list [ hour, min, sec,
  milli ]) to a readable string.
  
    Example  
    gap> HMSMSec(Factorial(10));
    [ 1, 0, 28, 800 ]
    gap> SecHMSM([1,10,5,13]);
    4205013
    gap> StringTime([1,10,5,13]);
    " 1:10:05.013"
  
  
  27.10-10 SecondsDMYhms
  
  SecondsDMYhms( DMYhms )  function
  
  returns  the number of seconds from 01-Jan-1970, 00:00:00, to the time given
  by  DMYhms,  which  must  be  a  list  of the form [ day, month, year, hour,
  minute,  second  ].  The remarks on the Gregorian calendar in the section on
  DayDMY  (27.10-4)  apply  here as well. The last three arguments must lie in
  the appropriate ranges.
  
  27.10-11 DMYhmsSeconds
  
  DMYhmsSeconds( secs )  function
  
  This is the inverse function to SecondsDMYhms (27.10-10).
  
    Example  
    gap> SecondsDMYhms([ 9, 9, 2001, 1, 46, 40 ]);
    1000000000
    gap> DMYhmsSeconds(-1000000000);
    [ 24, 4, 1938, 22, 13, 20 ]
  
  
  
  27.11 Obtaining LaTeX Representations of Objects
  
  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 LaTeXStringDecompositionMatrix (71.11-5) 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.