Tech Note 15: Using the NSBStringLib Library

May 01, 2008

© NSB Corporation. All rights reserved.

NSBStringLib adds a number of handy functions to NS Basic for doing string manipulation and data formatting.

To use it, add NSBStringLib.prc to your project as a resource. It is a small file, about 5k in size. Initialise it in your Startup code as follows:

     loadLibrary "NSBStringLib","STR"   'case is important
To see how each of these functions works, see the StringLibUse sample project.

Files included:
NSBStringLib.INF The info file for StringLib. Put this in your \nsbasic\lib folder.
NSBStringLib.prc The library. Put this into your \nsbasic\lib folder and add it to your project.
StringLibUse.prj A sample project that demonstrates the functions.


Version()

Returns the version of NSBStringLib as a string

Replace(str,find,replace,count)

Returns a string in which a specified substring has been replaced with another substring a specified number of times. Do not assign the result to str - it needs to be a different variable.

str Required. String containing substring to replace.
find Required. Substring being searched for.
replace Required. Replacement substring. If replace string is longer than find string, then str should be padded in advance to be long enough to handle the increased length.
count Optional. Number of substring substitutions to perform. Must be used in conjunction with start. Must be a short variable.

StrReverse(String)

Returns a string in which the character order of a specified string is reversed.

Space(num)

Returns a string consisting of the specified number of spaces. Num must be a Short variable.

CreateString(number, ch)

Returns a repeating character string of the length specified. Number must be a Short variable.

MonthName(month, abbreviate)

Returns a string indicating the specified month.
monthRequired. The numeric designation of the month. For example, January is 1, February is 2, and so on.
abbreviate Optional. Boolean value that indicates if the month name is to be abbreviated. If omitted, the default is False, which means that the month name is not abbreviated.

WeekdayName(weekday, abbreviate,firstdayofweek)

Returns a string indicating the specified day of the week.

weekday Required. The numeric designation for the day of the week. Numeric value of each day depends on setting of the firstdayofweek setting.
abbreviate Optional. Boolean value that indicates if the weekday name is to be abbreviated.
firstdayofweek Optional. Numeric value indicating the first day of the week.
 
		0 Use preferences settings.
		1 Sunday (default) 
		2 Monday3 Tuesday
		4 Wednesday
		5 Thursday
		6 Friday
		7 Saturday 

InstrRev(str, find, start)

Returns the position of an occurrence of one string within another, from the end of string.

InStrRev returns the following values:
find is zero-length 0
find is Null Null
str is zero-length start
str is Null Null
str is not found 0
str is found within find Position at which match is found
start > Len(str) 0

LSet(str1, str2)

LSet left aligns the string str1 within the string str2. If str2 is shorter than str1, str1 is truncated. If str1 is longer, str2 is padded to the same length with spaces.
str1 Required. Name of variable for result.
str2 Required. String expression to be left-aligned within str1.

RSet(str1, str2)

RSet right aligns the string str1 within the string str2. If str2 is shorter than str1, str1 is truncated. If str1 is longer, str2 is padded to the same length with spaces.
str1 Required. Name of string variable.
str2 Required. String expression to be right-aligned within str1.

FormatNumber(expr, numDig, format)

Returns a string formatted as a number.

expr Required. Expression to be formatted.
numDigNumeric value indicating how many places to the right of the decimal are displayed.
format IncludeLeadingDigit+UseParensForNegativeNumbers+GroupDigits
IncludeLeadingDigit Tristate constant that indicates whether or not a leading zero is displayed for fractional values.
UseParensForNegativeNumbers Tristate constant that indicates whether or not to place negative values within parentheses.
GroupDigits Tristate constant that indicates whether or not numbers are grouped using the group delimiter specified in the control panel.
Values for Format
0 ALL_DEFAULT (IncludeLeadingDigit = true, UseParensForNegativeNumbers = false, GroupDigits = false)
1 INCLUDE_LEADING_DIGIT_FALSE
2 INCLUDE_LEADING_DIGIT_TRUE
4 USE_PARENTS_FOR_NEGATIVE_NUMBER_FALSE
8 USE_PARENTS_FOR_NEGATIVE_NUMBER_TRUE
16 GROUP_DIGIT_FALSE
32 GROUP_DIGIT_TRUE

FormatTime(time, format)

Returns an expression formatted as a time. Time must be float.
Values for format:
0 tfColon
1 tfColonAMPM 1:00 pm
2 tfColon24h 13:00
3 tfDot
4 tfDotAMPM 1.00 pm
5 tfDot24h 13.00
6 tfHoursAMPM 1 pm
7 tfHours24h 13
8 tfComma24h 13,00
64 is for preference settings

FormatDate(date, format)

Returns a string formatted as a date. Date must be float. Format is one of the following:
0 dfMDYWithSlashes 12/31/95
1 dfDMYWithSlashes 31/12/95
2 dfDMYWithDots 31.12.95
3 dfDMYWithDashes 31-12-95
4 dfYMDWithSlashes 95/12/31
5 dfYMDWithDots 95.12.31
6 dfYMDWithDashes 95-12-31
7 dfMDYLongWithComma Dec 31, 1995
8 dfDMYLong, 31 Dec 1995
9 dfDMYLongWithDot 31. Dec 1995
10 dfDMYLongNoDay Dec 1995
11 dfDMYLongWithComma Dec, 1995
12 dfYMDLongWithDot 1995.12.31
13 dfYMDLongWithSpace 1995 Dec 31
14 dfMYMed Dec '95
15 dfMYMedNoPost Dec 95 (added for French 2.0 ROM)
From preferences:
64 is for short date
65 is for long date

FormatPercent(expression, numDig, format)

Returns a string formatted as a percentage (multiplied by 100) with a trailing % character.

expression Expression to be formatted.
numDig Numeric value indicating how many places to the right of the decimal are displayed.
format IncludeLeadingDigit+UseParensForNegativeNumbers+GroupDigits

Values for Format:
IncludeLeadingDigit Tristate constant that indicates whether or not a leading zero is displayed for fractional values.
UseParensForNegativeNumbers Tristate constant that indicates whether or not to place negative values within parentheses.
GroupDigits Tristate constant that indicates whether or not numbers are grouped using the group delimiter specified in the control panel.
0 ALL_DEFAULT (IncludeLeadingDigit = true, UseParensForNegativeNumbers = false, GroupDigits = false)
1 INCLUDE_LEADING_DIGIT_FALSE
2 INCLUDE_LEADING_DIGIT_TRUE
4 USE_PARENTS_FOR_NEGATIVE_NUMBER_FALSE
8 USE_PARENTS_FOR_NEGATIVE_NUMBER_TRUE
16 GROUP_DIGIT_FALSE
32 GROUP_DIGIT_TRUE

FormatCurrency(expression, numDig, format)

Returns a string formatted as a currency value using the currency symbol $.

expression Expression to be formatted.
numDig Numeric value indicating how many places to the right of the decimal are displayed.
format IncludeLeadingDigit+UseParensForNegativeNumbers+GroupDigits

Values for Format:
IncludeLeadingDigit Tristate constant that indicates whether or not a leading zero is displayed for fractional values.
UseParensForNegativeNumbers Tristate constant that indicates whether or not to place negative values within parentheses.
GroupDigits Tristate constant that indicates whether or not numbers are grouped using the group delimiter specified in the control panel.
0 ALL_DEFAULT (IncludeLeadingDigit = true, UseParensForNegativeNumbers = false, GroupDigits = false)
1 INCLUDE_LEADING_DIGIT_FALSE
2 INCLUDE_LEADING_DIGIT_TRUE
4 USE_PARENTS_FOR_NEGATIVE_NUMBER_FALSE
8 USE_PARENTS_FOR_NEGATIVE_NUMBER_TRUE
16 GROUP_DIGIT_FALSE
32 GROUP_DIGIT_TRUE