GAP (ref) - Chapter 27: Strings and Characters

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

27 Strings and Characters
27.1 IsChar and IsString
27.1-1 IsChar
27.1-2 IsString
27.1-3 Strings As Lists
27.1-4 Printing Strings
27.2 Special Characters
27.3 Triple Quoted Strings
27.4 Internally Represented Strings
27.4-1 IsStringRep
27.4-2 ConvertToStringRep
27.4-3 CopyToStringRep
27.4-4 IsEmptyString
27.4-5 EmptyString
27.4-6 CharsFamily
27.5 Recognizing Characters
27.5-1 IsDigitChar
27.5-2 IsLowerAlphaChar
27.5-3 IsUpperAlphaChar
27.5-4 IsAlphaChar
27.6 Comparisons of Strings
`27.6-1 \=`
`27.6-2 \<`
27.7 Operations to Produce or Manipulate Strings
27.7-1 DisplayString
27.7-2 DEFAULTDISPLAYSTRING
27.7-3 ViewString
27.7-4 DEFAULTVIEWSTRING
27.7-5 PrintString
27.7-6 String
27.7-7 StripLineBreakCharacters
27.7-8 HexStringInt
27.7-9 StringPP
27.7-10 WordAlp
27.7-11 LowercaseString
27.7-12 LowercaseChar
27.7-13 UppercaseString
27.7-14 UppercaseChar
27.7-15 SplitString
27.7-16 ReplacedString
27.7-17 NormalizeWhitespace
27.7-18 NormalizedWhitespace
27.7-19 RemoveCharacters
27.7-20 JoinStringsWithSeparator
27.7-21 Chomp
27.7-22 StartsWith
27.7-23 StringFormatted
27.7-24 NumbersString
27.7-25 StringNumbers
27.7-26 StringOfMemoryAmount
27.8 Character Conversion
27.8-1 IntChar
27.8-2 CharInt
27.8-3 SIntChar
27.8-4 CharSInt
27.9 Operations to Evaluate Strings
27.9-1 Int
27.9-2 Rat
27.9-3 IntHexString
27.9-4 Ordinal
27.9-5 EvalString
27.9-6 CrcString
27.9-7 HexSHA256
27.9-8 Pluralize
27.10 Calendar Arithmetic
27.10-1 DaysInYear
27.10-2 DaysInMonth
27.10-3 DMYDay
27.10-4 DayDMY
27.10-5 WeekDay
27.10-6 StringDate
27.10-7 HMSMSec
27.10-8 SecHMSM
27.10-9 StringTime
27.10-10 SecondsDMYhms
27.10-11 DMYhmsSeconds
27.11 Obtaining LaTeX Representations of Objects

### 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 `'`.

    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.

    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.

    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.8-3), or `AppendTo` (9.8-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.

    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 `Print` (6.3-4) that are contained in the string (`\n` characters, see 27.2), 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

#### 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.8-3), or `AppendTo` (9.8-3) 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 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.

    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.

    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 analogous 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.

    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.

    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.

    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.

    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).

    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 )`.

    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.

    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.

    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).

    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.

    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.

    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.

    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.

    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`.

    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.

    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 omitted, the bracket is treated as `{id}` with no `format`.

`id` is interpreted as follows:

An integer `i`

  Take the `i`th 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 `j`th 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`.

    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).

    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).

    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.

    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 ]`.

    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 ]`.

    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.

    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.

    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.

    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.

    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.

    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.

    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.8-7) and `HexSHA256` (27.9-7).

    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.

    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 \neq 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.

    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.

    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 ]`.

    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.

    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).

    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.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind

generated by GAPDoc2HTML