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