I stone got crazy when I saw somebody run down them strings with a bottleneck. My eyes lit up like a Christmas tree and I said that I had to learn.
— Muddy Waters

Strings.

An apology

I know, I ranted about people insisting on parsing strings in OpenSCAD, and then I go and include 23 or so string processing routines in The GHOUL. What gives? Well, some of these are trivial, no doubt, some are only here to show what’s possible, or because there’s a cute trick in the code, and some are here because I needed them, because—​of all things—​I’m writing an encoding library in OpenSCAD. I know. It’s like climbing Everest on a bicycle. I never claimed to be sane.

Alphabetical()

Alphabetical(String,IgnoreCase=false)

  • String, a string…​

  • IgnoreCase, Boolean, case is ignored if true.

Alphabetical() places all characters in a string in alphabetical order, or rather, in the order of where they appear in AsciiCharacters. Uppercase characters are grouped at the beginning, unless IgnoreCase is true.

echo(Alphabetical("Hello World 42."));

ECHO: "  .24HWdellloor"

AsciiMapString()

AsciiMapString(String)

  • String, string to map onto Ascii code.

A bit like the OpenSCAD native ord() but not really. AsciiMapString() returns an array filled with the Ascii codes of the input string characters. See the AsciiCharacters declaration in Defenitions/Constants.scad; only tab, line-feed and carriage-return, space and printable characters up to '~' (Ascii 9,10,13 and 32 through 126) are included in this string. AsciiMapString() is just the Ascii pre-seeded version of MapString().

While we’re here; do you really know what a 'carriage-return' actually is? I hope you’re too young to…​

Array=AsciiMapString("Hello!");
echo(Array);

ECHO: [72, 101, 108, 108, 111, 33]

FillString()

FillString(Repetitions,Chars)=

  • Repetitions, integer, repetitions of Chars pattern.

  • Chars, string, pattern to be repeated.

FillString() returns a string, containing the repeated Chars pattern.

echo(FillString(3,"8F"));

ECHO: "8F8F8F"

IsHex()

IsHex(String,Length)

  • String, string to check.

  • Length, integer, length to check for, defaults to undef.

IsHex() returns true if String is a hexadecimal number of Length characters. Leave Length undef if a length check is not needed. A single initial "#" character is ignored.

IsNullOrEmptyString()

IsNullOrEmptyString(String)

  • String, potential empty string or undef parameter.

IsNullOrEmptyString() checks whether String is either undef or empty ("") and returns true if this is the case. Any other value results in false.

echo(IsNullOrEmptyString());
echo(IsNullOrEmptyString(""));
echo(IsNullOrEmptyString("False"));
echo(IsNullOrEmptyString(5));
echo(IsNullOrEmptyString(undef));

ECHO: true
ECHO: true
ECHO: false
ECHO: false
ECHO: true

IsString()

IsString(String)

  • String, potential string.

IsString() checks whether String is a string returns true if this is the case. Any other value results in false.

Tip An empty string is also a string. 
echo(IsString());
echo(IsString(""));
echo(IsString("False"));
echo(IsString(5));
echo(IsString(undef));

ECHO: false
ECHO: true
ECHO: true
ECHO: false
ECHO: false

IsUniCode()

IsUniCode(String)

  • String, string to check.

IsUniCode() returns true if String has four characters, all of which are from 'HexCharLow', i.e., [0…​9,A…​F,a…​f]. A single initial "#" character is ignored.

LeftString()

LeftString(String,End)

  • String, a string.

  • End, last position in String or number of positions from the end of String.

LeftString() returns the left part of String, up to and including index=End. End can be a positive number, or a negative number. In the latter case, it is interpreted as "the abs(End) character from the end of String", i.e., all but the last so many characters.

Note Just like the 'regular' indexable variables such as arrays, tuples and vectors, string indices in The GHOUL use circular indexing so you can do things like LeftString(String,-5), or LeftString(String,25) on a 15 letter string and get a valid (though possibly unexpected) result. Check out the circular indexing sidebar in the array documentation; essentially, the index -1 denotes the last character of a string, i.e., String[len(String)]. 
echo(LeftString("Hello World!",5));

ECHO: "Hello"

echo(LeftString("Hello World!",-5));

ECHO: "Hello Wo"

Yes, I’m treating RightString() out of sequence here, but it seemed a logical thing to do…​

RightString()

RightString(String,Start)

  • String, a string.

  • Start, first position in String or number of positions from the beginning of String.

RightString() returns the right part of String, from and including index=Start. Start can be a positive number, or a negative number. In the latter case, it is interpreted as "the abs(Start) character from the end of String", i.e, the last so many characters.

Also see the note at LeftString().

echo(RightString("Hello World!",5));

ECHO: "o World!"

echo(RightString("Hello World!",-5));

ECHO: "orld!"

LowerCase()

LowerCase(String)

  • String, string.

LowerCase() returns String in all lower case, non-letter characters pass through unchanged.

echo(LowerCase("This is The GHOUL."));

ECHO: "this is the ghoul."

UpperCase()

UpperCase(String)

  • String, string.

UpperCase() turns lowercase letters in a string to uppercase, all non-letter symbols are left unchanged.

MapString()

MapString(String,ResultArray=PrintableCodes,SearchString=PrintableCharacters)

  • String, string to map onto ResultArray.

  • ResultArray, array of return values that String is mapped onto. Default is PrintableCodes.

  • SearchString, string to search for characters from String. Default is PrintableCharacters.

MapString() searches SearchString for each character in String and maps it onto ResultArray, it returns an array filled with the values from ResultArray corresponding to the locations in SearchString of the input String characters. AsciiMapString() is a strictly 'string-to-Ascii-code' interpretation of this function.
MapString() is used in the SimpleText() module family to find character widths and kernings. Because the default SearchString is PrintableCharacters, MapString() can, in all cases but a few, be called with just the input String and a ResultArray, as long as ResultArray has a mapping value for every value in PrintableCharacters, or in other words: they have the same length.

Tip PrintableCharacters is declared in TheGHOUL/Lib/Definitions/Constants.scad and contains a 'space' and: !"#$%&'()*+,-./0123456789:;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ 
SString="ABCDabcd1234";
RArray=[1,2,3,4,1,2,3,4,1,2,3,4];
Result=MapString("Bb2",RArray,SString);
echo(Result);

ECHO: [2, 2, 2]

SString="The quick brown fox jumps over the lazy dog.";
RArray=RangeToTuple[0:43];
Result=MapString("over the fox",RArray,SString);
echo(Result);

ECHO: [12, 27, 2, 11, 3, 31, 1, 2, 3, 16, 12, 18]

PadString()

PadString(String,Length=3,Padding="")

  • String, string.

  • Length, length to pad String to.

  • Padding, single character to pad String with.

PadString() does what it says. The string-equivalent of PadTuple().

echo(PadString("TheGHOUL",Length=11,Padding="."));

ECHO: "TheGHOUL..."

Prefix()

Prefix(String,Length=4,Prefix="0")

  • String, string.

  • Length, length to 'prefix' String to.

  • Prefix, single character to prefix String with.

Prefix() increases a string’s (unknown) length to a certain length with (a series of) one character.

ReplaceCharacters()

ReplaceCharacters(InChars,OutChars,String)

  • InChars, string, character(s) to replace.

  • OutChars, string, replacement character(s).

  • String, string.

ReplaceCharacters() replaces InChars characters with OutChars characters. If no replacement character is specified, the character is scrubbed.

echo(ReplaceCharacters("TUeH","DOa","TheGHOUL"));

ECHO: "DhaGOOL"

ScrubCharacters()

ScrubCharacter(InChars,String)

  • InChars, string, character(s) to remove.

  • String, string.

ScrubCharacters() returns the string with InChars characters removed.

echo(ScrubCharacters("LH","TheGHOUL"));

ECHO: "TheGOU"

ScrubRepeated()

ScrubRepeated(String)

  • String, string.

ScrubRepeated() returns the string with all but the first occurrences of any character removed.

echo(ScrubRepeated("Abacadabra Hocus Pocus"));

ECHO: "Abacdr HousP"

SetDecimals()

SetDecimals(Value,Decimals,Padding)

  • Value, a scalar.

  • Decimals, an integer, number of decimals in the returned string.

  • Padding, padding character to fill trailing empty positions. Default=0.

SetDecimals() takes a scalar and converts it to a string with the requested number of digits after the decimal point. Useful for right aligning output &c.

Note Adding trailing zeroes to a number containing a decimal point might give a false impression about the number of significant figures; perhaps use a space character " " for Padding if you want to prevent this. 
String=SetDecimals(1.23456,3);
echo(String);

ECHO: "1.234"

String=SetDecimals(1.23,3);
echo(String);

ECHO: "1.230"

String=SetDecimals(1.23,3," ");
echo(String);

ECHO: "1.23 "

StringToDecimal()

StringToDecimal(String)

  • String, string representing a real number.

StringToDecimal() returns the real number value represented by String.

StringToTuple()

StringToTuple(String,OutputLength=undef,Padding="")

  • String, a string.

  • Padding, padding character to fill empty trailing spaces when OutputLength is greater than len(String)-1.

  • OutputLength, the desired length of the resulting array.

Takes a string and breaks it up into an array of single characters, OutputLength long. If OutputLength is greater than len(String)-1, the resulting array is padded with Padding. If OutputLength=undef, the array simply contains the individual characters of String.

Array=StringToTuple("Value",8,"");
echo(Array);

ECHO: ["V", "a", "l", "u", "e", "", "", "", ""]

TupleToString()

TupleToString(StringsArray)

  • StringsArray, an array of string characters.

TupleToString() takes an array of characters and chains them together into a single string.

String=TupleToString(["V", "a", "l", "u", "e"]);
echo(String);

ECHO: "Value"

SubString()

SubString(String,Start,End)

  • String, a string.

  • Start, the first 0-base character (inclusive) in String to be returned.

  • End, the last 0-base character (inclusive) in String to be returned. End may be negative, in which case it takes on the meaning of "this many characters from the end".

SubString() returns a sub-set of the characters in String, delimited by the Start and End values. A negative End value will drop End characters from the end of String.

echo(SubString("0123456",2,4));

ECHO: "234"

echo(SubString("0123456",2,-1));

ECHO: "2345"

UniCodeMapString()

UniCodeMapString(String)

  • String, string.

UniCodeMapString() returns an array filled with the Unicodes of the input string.