Nasal library/string

This article is a stub. You can help the wiki by expanding it.

String Handling

This page contains description of functions available in "$FG_ROOT\data\Nasal\strings.nas". For string related functions in Nasal also see Nasal library page. UTF8 specific functions are from Nasal core library.

One Character Functions

string.isalnum()

Checks whether the character is an ASCII alphanumeric character (either a letter `A–Z`/`a–z` or a digit `0–9`).

string.isalnum();

string.isalpha()

Checks whether the character is an ASCII alphabetic letter (either uppercase `A–Z` or lowercase `a–z`).

string.isalpha();

string.isascii()

Checks whether the character code is a valid ASCII value (in the range 0–127).

string.isascii();

string.isblank()

Checks whether the given character code represents a blank character (a space or a horizontal tab).

string.isblank();

string.iscntrl()

Checks whether the given character code represents an ASCII control character (in the range 1–31 or 127).

string.iscntrl();

string.isdigit()

Checks whether the character represents a decimal digit (0–9).

string.isdigit();

string.isgraph()

Checks whether the character is a graphical character, meaning any visible character that is either alphanumeric or punctuation, excluding whitespace.

string.isgraph();

string.islower()

Checks whether the character is a lowercase ASCII letter (`a–z`).

string.islower();

string.isprint()

Checks whether the character is printable, meaning it is either a visible graphical character or a space character.

string.isprint();

string.ispunct()

Checks whether the given character code represents a punctuation character (based on standard ASCII punctuation ranges).

string.ispunct();

string.isspace()

Checks whether the character is a whitespace character (space, tab, newline, vertical tab, form feed, or carriage return).

string.isspace();

string.isupper()

Checks whether the character is an uppercase ASCII letter (A–Z).

string.isupper();

string.isxdigit()

Checks whether the character represents a valid hexadecimal digit (0–9, a–f, or A–F).

string.isxdigit();

string.isxspace()

Checks whether the character is an extended whitespace character — includes all standard whitespace characters (space, tab, vertical tab, form feed, carriage return) plus the newline character, making it an extended version of isspace().

string.isxspace();

string.toupper()

Converts a lowercase ASCII letter to its corresponding uppercase letter; if the character is not lowercase, it is returned unchanged.

string.toupper();

string.tolower()

Converts an uppercase ASCII letter to its corresponding lowercase letter; if the character is not uppercase, it is returned unchanged.

string.tolower();

String Functions

string.icmp(a,b)

Case insensitive string compare function.

string.icmp(a,b);

string.imatch(a,b)

Case insensitive match function.

string.imatch(a,b);

For example:

• string.imatch("alpha","beta") -> 0
• string.imatch("alpha","alpha") -> 1
• string.imatch("","alpha") -> 0
• string.imatch("","") -> 1

string.join(sep,list)

Join all elements of a list inserting a separator between every two of them. See split().

string.join(sep,list);

string.lc(str)

Return string converted to lower case letters.

string.lc(str);

string.match(str, patt)

Check if string <str> matches shell style pattern <patt>

# Rules:
# ?   stands for any single character
# *   stands for any number (including zero) of arbitrary characters
# \   escapes the next character and makes it stand for itself; that is:
#     \? stands for a question mark (not the "any single character" placeholder)
# []  stands for a group of characters:
#     [abc]      stands for letters a, b or c
#     [^abc]     stands for any character but a, b, and c  (^ as first character -> inversion)
#     [1-4]      stands for digits 1 to 4 (1, 2, 3, 4)
#     [1-4-]     stands for digits 1 to 4, and the minus
#     [-1-4]     same as above
#     [1-3-6]    stands for digits 1 to 3, minus, and 6
#     [1-3-6-9]  stands for digits 1 to 3, minus, and 6 to 9
#     [][]       stands for the closing and the opening bracket (']' must be first!)
#     [^^]       stands for all characters but the caret symbol
#     [\/]       stands for a backslash or a slash  (the backslash isn't an
#                escape character in a [] character group)
#
#     Note that a minus can't be a range delimiter, as in [a--e],
#     which would be interpreted as any of a, e, or minus.
#
# Example:

string.match(name, "*[0-9].xml"); ... true if 'name' ends with digit followed by ".xml"

string.normpath(path)

Removes superfluous slashes, empty and "." elements, expands all ".." elements keeping relative paths, and turns all backslashes into slashes. The result will start with a slash if it started with a slash or backslash, it will end without slash.

string.normpath(path);

See also resolvepath() function, which can be used to test if a file exists.

string.replace(str,old,new)

Replace all occurrences of 'old' by 'new'.

string.replace(str,old,new);

string.scanf(test,format,result)

Simple scanf function. Takes an input string, a pattern, and a vector. It returns 0 if the format didn't match, and appends all found elements to the given vector.

Return values:

-1 string matched format ending with % (i.e. more chars than format cared about)
 0 string didn't match format                                                   
 1 string matched, but would still match if the right chars were added          
 2 string matched, and would not if any character would be added                

var r = string.scanf("comm3freq123.456", "comm%ufreq%f", var result = []);

The result vector will be set to [3, 123.456].

string.squeeze(s,length)

Shorten string s to length by replacing characters in the middle by '...'. (since 2020.4 / next as of 03.08.2024)

var r = string.squeeze("FooBarBaz", 9);

r now contains the string "Foo...Baz".

string.trim(str,lr[,func])

Trim spaces at the left (lr < 0), at the right (lr > 0), or both (lr = 0) is default. An optional function argument defines which characters should be trimmed:

string.trim(a);                                    # trim spaces             
string.trim(a, 1, string.isdigit);                 # trim digits at the right
string.trim(a, 0, func(c) c == `\\` or c == `/`);  # trim slashes/backslashes

string.uc(str)

Return string converted to upper case letters.

string.uc(str);

string.compileTemplate(template,type=nil)

Get a function out of a string template for fast insertion of template parameters. This allows to use the same templates as with most available tile mapping engines (eg. Leaflet, Polymaps). Return a callable function object on success, and nil if parsing the templated fails.

string.compileTemplate(template);

Example (Build MapQuest tile url):

 var makeUrl = string.compileTemplate(                          
   "http://otile1.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.jpg"    
 );                                                             
 print( makeUrl({x: 5, y: 4, z: 3}) );                          

Output:   http://otile1.mqcdn.com/tiles/1.0.0/map/3/5/4.jpg

UTF8 String Functions (Core)

utf8.chstr(unicode)

Returns a string containing the UTF8 representation of the specified unicode character value.

utf8.strc(string, index)

Returns the unicode character at the specified index within the UTF8 string. Dies on encoding error or overrun.

utf8.substr(string, start, len=nil)

As for regular substr(), but the indices are of UTF8 characters intead of bytes. Dies on encoding error or overflow.

utf8.size(string)

As for regular size() when called on a string, but returns the number of UTF8 unicode characters instead of bytes. Dies on encoding error.

utf8.validate(string, replace=`?`)

Checks the string for UTF8 validity. At every byte position where an encoding error is found, it replaces that byte with the specified replacement character (default is `?`). Note that the second argument is a number, not a string.