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

string.isalnum();

string.isalpha()

string.isalpha();

string.isascii()

string.isascii();

string.isblank()

string.isblank();

string.iscntrl()

string.iscntrl();

string.isdigit()

string.isdigit();

string.isgraph()

string.isgraph();

string.islower()

string.islower();

string.isprint()

string.isprint();

string.ispunct()

string.ispunct();

string.isspace()

string.isspace();

string.isupper()

string.isupper();

string.isxdigit()

string.isxdigit();

string.isxspace()

string.isxspace();

string.toupper()

string.toupper();

string.tolower()

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.