Tech Note 15: Using the NSBStringLib Shared Library

Oct 27, 2003

© NSB Corporation. All rights reserved.

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

To use it, download NSBStringLib.prc to your device. 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 download it to your device (or POSE).

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

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 download it to your device (or POSE).
StringLibUse.prj	A sample project that demonstrates the functions.

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