Adding and Subtracting Numeric Values

Adding and subtracting numbers in AutoLISP works just like you might have learned in elementary school, with one slight difference: Instead of placing a + or − operator symbol between each number as you normally would, the AutoLISP + or - function must be the first atom in a list. An atom is an element or item within a list. The + and - functions can add or subtract any number of integer or real numeric values, and they return an integer or real numeric value. An integer is returned when all the values passed to the function are integers; otherwise, a real value is returned.

The following shows the syntax of the + and - functions:

(+ [numberN ...])
(- [numberN ...])

The numberN argument represents the numeric values you want to add together or subtract from each other. The numberN argument is optional and can be more than one value. If no value is passed to the + or - functions, 0 is returned.

Here are some examples of adding and subtracting numbers with the + and - functions, along with the values that are returned:

(+ 5 2 3)
10
(+ 5.0 2 3)
10.0
(+ 5.0 2.25 0.25)
7.5
(- 2 3)
-1
(+ (- 1.625 0.125) 1)
2.5

In addition to the + and - functions, you can use the 1+ function to increment (or 1- to decrement) a value by 1. If you need to increment or decrement a value by more than 1, you will need to use the + and - functions. The 1+ and 1- functions are a great way to create a counter in a looping expression. I explain how to use looping expressions in Chapter 5, “Requesting Input and Using Conditional and Looping Expressions.”

The following shows the syntax of the 1+ and 1- functions:

(1+ number)
(1- number)

The number argument represents the numeric value that should be incremented or decremented by 1.

Here are examples of incrementing or decrementing a number with the 1+ and 1- functions, along with the values that are returned:

(setq cnt 0)
0
(1+ cnt)
1
(1- cnt)
-1

Multiplying and Dividing Numeric Values

Multiplying and dividing numeric values is an effective way to calculate a new scale factor to increase or decrease the scale factor of an object, or even to figure out how many objects of a specific size might fit into an area or along a linear path. Use the * function to multiply any number of integer or real numeric values and return the resulting product. Using the / function returns the quotient after dividing any number of numeric values. The * and / functions return an integer or real numeric value. An integer is returned by the functions when all the values passed to the function are integers; otherwise, a real numeric value is returned.

The following shows the syntax of the * and / functions:

(* [numberN ...])
(/ [numberN ...])

The numberN argument represents the numeric values you want to multiply or divide by each other. The numberN argument is optional and can be more than one value. If no value is passed to the * or / function, 0 is returned.

Here are examples of multiplying and dividing numbers with the * and / functions, along with the values that are returned:

(* 5 3)
15
(* 5.0 2 3)
30.0
(/ 5 2)
2
(/ 5.0 2)
2.5

When dividing numbers, you can use the AutoLISP rem function to return the remainder of the first number after it has been divided by all the other numbers supplied to the function. The rem function can take any number of numeric values; the function returns 0 when no values are passed to it. The following demonstrates the rem function:

(/ 10.0 3)
3.33333
(rem 10.0 3.0)
1.0

AutoLISP includes a function named gcd that can be used to return the greatest common denominator of two integer values. The gcd function requires two integer values, and it returns an integer that represents the greatest common denominator of the provided values. Here are two examples:

(gcd 5 2)
1
(gcd 54 81)
27

Using Other Basic Math Functions

Most of your math function needs should be met with the basic math functions that I previously covered, but you should be aware of some other basic math functions. These other functions allow you to get the minimum or maximum number in a range of values or determine if a numeric value is equal to 0 or is negative.

The following explains some of the other basic math functions that are available as part of AutoLISP:

1. min and max

   The min and max functions accept any integer or real numeric values. The min function returns the smallest numeric value from those that are passed to it, whereas the max function returns the largest numeric value. A real value is returned by the function, except when the function is passed only integer values—in that case, an integer value is returned. If no numeric value is passed to either function, 0 is returned.

   The following are examples of the min and max functions:

   (min 9 1 1976 0.25 100 -25)
   -25.0
   (max 9 1 1976 0.25 100 -25)
   1976.0
   (max 9 1 1976 100 -25)
   1976

2. minusp and zerop

   The minusp and zerop functions accept an integer or real numeric value. The minusp function returns T if the value that it was passed is negative, or it returns nil if the value was positive. The zerop function also returns T or nil; T is returned if the value passed is equal to 0. The zerop function can help you avoid dividing a number by 0 or seeing if a system variable is set to 0.

   The following are examples of the minusp and zerop functions:

   (minusp 25)
   nil
   (minusp -25)
   T
   (zerop 25)
   nil
   (zerop 0)
   T

   For more information on the minusp and zerop functions, see the AutoCAD Help system.

logior

The logior function allows you to combine several bits into a single bit-coded value and ensures that a bit is added only once to the resulting bit-coded value. Although you can use the + function to add several bits together, that function simply adds several values together and returns the resulting value, which might return a bit-coded value with a different meaning. For example, the bits 1 and 4 are equal to the bit-coded value of 5:

; Final result is a bit-coded value of the bits 1 and 4
(logior 1 4)
5
; Final result is an integer of 5
(+ 1 4)
5

Adding the bits 1, 2, and 5 with the logior function results in the bit-coded value of 7.

; Final result is a bit-coded value of the bits 1, 2, and 4
(logior 1 2 5)
7

Were you expecting a value of 8 maybe? The 1 bit is added only once because the logior function recognizes that the 1 bit is provided individually and as part of the bit-coded value of 5 in the previous example. If you were to add the same numbers (1, 2, and 5) together with the + function, the result would be 8 and would mean something different. A value of 8 is a bit in and of itself.

; Final result is an integer of 8 and not a bit-coded value of the bits 1, 2, and 4
(+ 1 2 5)
8

Here is the syntax of the logior function:

(logior [bitN ...])

The bitN argument represents the bits you want to combine. If no bit is passed to the function, 0 is returned.

The following examples add the provided bits together into a bit-coded value of 35 with the logior function. The bits 1, 2, and 32 represent the ENDpoint, MIDpoint, and INTersection running object snap settings. The second expression returns a value of 35 as well, and because 3 is a bit-coded value that represents both bits 1 and 2, the logior function will add a bit only once to the bit-coded value it returns. If you used the + function instead, it would be easy to add a bit more than once to a bit-coded value.

; Returns the sum of the bits 1, 2, and 32
(setq new_osmode (logior 1 2 32))
35
; Returns the sum of the bits 1, 2, 3, and 32
; Bit 3 is a bit-coded value containing 1 and 2
(logior 1 2 3 32)
35

logand

The logand function is used to determine whether a specific bit or bit-coded value is part of another bit-coded value. This type of comparison in a program can be helpful when you need to handle specific conditions in the AutoCAD environment, such as making sure that the current layer is not frozen or locked when you're creating or selecting objects, or making sure a specific running object snap is set.

Here is the syntax of the logand function:

 (logand [bitN ...])

The bitN argument represents the bits you want to test for comparison. If no value is passed to the function, 0 is returned.

The following examples use the logand function to determine if a bit is common with the provided bits or bit-coded values. Bit 2 represents the MIDpoint running object snap; a bit-coded value of 12 represents the CENter and QUAdrant running object snaps; and the bit-coded value of 34 represents the running object snaps MIDpoint and INTersection. The first example returns 0 because the bit 2 value is not part of the bit-coded value 12 (bit codes 4 and 8), whereas 2 is returned for the second example because bit 2 is part of the bit-coded value of 34 (bit codes 1, 2, and 32).

; Returns 0 because no bit codes are in
; common with the two numbers
(logand 2 12)
0
; Returns 2 because it is the common bit code
; in common with both numbers
(logand 2 34)
2s

If you want to add or remove a bit to or from a bit-coded value, you can use logand to verify whether a bit is already part of the bit-coded value. If 0 is returned by logand, the bit code is not part of the bit-coded value, so the bit could safely be added with the + function. If the bit is returned instead of 0, the bit is part of the bit-coded value and can be safely removed using the - function.

Other Bitwise Functions

In addition to the AutoLISP logior and logand functions, you can use these functions when working with bit-coded values:

1. ∼ (Bitwise NOT)

   The ∼ (bitwise NOT) function accepts a bit (integer) value and converts it into a binary number before performing a bitwise negation. The negation changes any 1 in the binary value to a 0, and any 0 to a 1. For example, an integer value of 32 expressed as a binary value is as follows:

   0000 0000 0000 0000 0000 0000 0000 0000
   0000 0000 0000 0000 0000 0000 0010 0000

   The binary value is read from lower right to upper left.

   When the ∼ (bitwise NOT) function is applied to a bit value of 32, it becomes a bit value of −33 and is expressed as the binary value

   1111 1111 1111 1111 1111 1111 1111 1111
   1111 1111 1111 1111 1111 1111 1101 1111 

   The following is an example of the ∼ (bitwise NOT) function:

   (∼ 32)
   -33

2. boole

   The AutoLISP boole function is used to perform a Boolean operation on two bit-coded (integer) values. The Boolean operations that can be performed are AND (1), XOR (6), OR (7), and NOR (8). For example, the AND Boolean operation can be used to see which bits are common between two bit-coded values. If an AND Boolean operation is performed on the bit-coded values 55 and 4135, a bit-coded value of 39 is returned.

   The following is an example of the boole function:

   (boole 1 55 4135)
   39

3. Lsh

   The AutoLISP lsh function accepts a bit (integer) value and converts it into a binary number before performing a bitwise shift by a specified number of bits. For example, you can shift the bit value of 1 by 3 bits to return the 8 bit value. A bit value of 1 is expressed as the binary value 1000 0000 (read left to right); the bitwise shift moves the 1 three bits to the right and it becomes a binary value of 0001 0000, or a bit value of 8.

   The following is an example of the lsh function:

   (lsh 1 3)
   8

For more information on the ∼ (bitwise NOT), boole, and lsh functions, see the AutoCAD Help system.

Working with Bit-Coded Values

The following exercise demonstrates how to work with bit-coded values. You'll create a custom function that allows you to toggle the state of the INTersection object snap. The current running object snap modes are stored in the osmode system variable, which contains a bit-coded value. The INTersection object snap is represented by the bit code 32.

1. At the AutoCAD Command prompt, type (setq cur_osmode (getvar "osmode")) and press Enter.

   The current value of the osmode system variable is assigned to the cur_osmode user-defined variable.

2. Type (logand 32 cur_osmode) and press Enter.

   The value 32 or 0 is returned. If 32 is returned, then the INTersection object snap mode is enabled.

3. Type osnap and press Enter.
4. When the Drafting Settings dialog box opens, verify the current state of the Intersection check box based on the results you got in step 2. Click Cancel.

   If 32 is returned by the logand function in step 2, the Intersection check box should be checked; otherwise it will be unchecked.

5. Type the following and press Enter:

   (defun c:ToggleINT ( / cur_osmode)
     (setq cur_osmode (getvar "osmode"))
     (if (= (logand 32 cur_osmode) 0)
       (setvar "osmode" (logior 32 cur_osmode))
       (setvar "osmode" (- cur_osmode 32))
     )
    (princ)
   )

6. Type toggleint and press Enter.

   The custom function checks the bit-coded value of the osmode system variable to see if bit code 32 is part of the value. If bit code 32 is not part of the bit-coded value, 32 is added to the current value of the osmode system variable with the logior function. Otherwise, 32 is subtracted from the osmode system variable.

7. Open the Drafting Settings dialog box and verify that the state of the Intersection check box has been changed. Click Cancel.
8. Type toggleint and press Enter.

   The previous state of the INTersection object snap mode is restored.

Returning the Length of a String

The AutoLISP strlen (short for string length) function returns the number of characters in a string. The following shows the syntax of the strlen function:

(strlen [string])

The string argument represents the string for which you want to know the length; the length is returned as an integer. Spaces in a string are counted as one character. The string argument is optional, and a length of 0 is returned if no argument is provided.

The following are examples of the strlen function and the values that are returned:

(strlen "Hello")
5
(strlen "  Hello  ")
9
(strlen "Product: %product%")
18

Searching for a Text Pattern in a String

In addition to wanting to know the number of characters in a string, you might want to know if a specific text pattern is contained in a string. This can be helpful if you want to create a custom find and replace program for text contained in an annotation object. The AutoLISP vl-string-search function takes a text pattern and compares that pattern to a string. The position at which the text pattern begins in the string is returned as an integer. If the text pattern is not found, nil is returned. The first character in a string is located in the 0 position. A string can contain multiple instances of the text pattern, but the vl-string-search function only returns the start position of the first instance of the text pattern.

The following shows the syntax of the vl-string-search function:

(vl-string-search pattern string [start])

The arguments are as follows:

1. pattern The pattern argument represents the text pattern that you want to search for in the string argument. The text pattern is case sensitive.
2. String The string argument represents the string that you want to search.
3. Start The start argument represents the starting position in the string argument where you want to begin searching for the text pattern specified by the pattern argument. The start argument is optional. If no argument is provided, searching for the text pattern starts at the 0 position.

The following are examples of the vl-string-search function and the values that are returned:

(vl-string-search "product" "Product: %product%")
10
(vl-string-search "Product" "Product: %product%")
0
(vl-string-search "program" "Product: %product%")
nil

Although the vl-string-search function can be used to search a string for a text pattern, the function is limited to searching only for that text pattern and in the case specified. If you have a need to search a string for multiple text patterns, the vl-string-search function is not very efficient by itself. You can use the wcmatch (short for wildcard match) function to help search a string for more complex text patterns with the use of wildcard pattern matching.

However, unlike the vl-string-search function, the wcmatch function returns T only if the wildcard pattern matches part or all of the string; otherwise, nil is returned if no match is found. If a match is found, it is up to you to try to find the text in the string that was matched. You can use the AutoLISP substr function along with a looping expression to get down to the substring that is a match. You'll learn more about the substr function in the “Replacing and Trimming Strings” section later in this chapter, and more about looping expressions in Chapter 5.

The following shows the syntax of the wcmatch function:

(wcmatch string pattern)

The arguments are as follows:

1. string The string argument represents the string that you want to search.
2. Pattern The pattern argument represents the wildcard text pattern that you want to search for in the string argument. For information on the wildcard characters that are supported, see the “wcmatch” topic in the AutoCAD Help system.

Here are examples of the wcmatch function and the values that are returned:

(wcmatch "W6X12" "W#X12")
T
(wcmatch "W*6" "W#X12")
nil

The AutoLISP strlen, vl-string-search, and wcmatch functions are all helpful in learning more about the length or characters in a string. Here are two additional functions that can be useful in finding out what characters are in a string:

1. vl-string-position

   Returns the position of a character in a string

2. vl-string-mismatch

   Returns the length of the characters that are at the beginning of and in common between two strings

For more information on these functions, see the AutoCAD Help system.

Replacing a Text Pattern in a String

A text pattern or set of characters in a string can be replaced with a new string or set of characters, making it easy to update an out-of-date part number or even a basic implementation of inline variable expansion. For additional information on inline variable expansion, see the “What Is Inline Variable Expansion?” sidebar.

The AutoLISP vl-string-subst (short for string substitution) function is commonly used to replace a text pattern in a string. Only the first instance of the matching text pattern is replaced, so you might need to run the vl-string-subst function several times on a string.

The following shows the syntax of the vl-string-subst function:

(vl-string-subst new_string pattern string [start])

The arguments are as follows:

1. new_string The new_string argument represents the string that you want to use as the replacement value if the text pattern specified by the pattern argument is found in the string argument.
2. Pattern The pattern argument represents the text pattern that you want to search for in the string argument.
3. String The string argument represents the string that you want to search.
4. Start The start argument represents the starting position in the string argument that you want to begin searching for the text pattern specified by the pattern argument. The start argument is optional. If no argument is provided, searching for the text pattern starts at the first position.

The following are examples of the vl-string-subst function and the values that are returned:

(vl-string-subst "career" "hobby" "Programming is my hobby.")
"Programming is my career."
(vl-string-subst "_" " " "Project 123 - ABC")
"Project_123 - ABC"

Listing 3.1 is a custom function that mimics the use of inline variable expansion. When the function is executed, it attempts to match the text between % (percent) signs with a user-defined variable. If the variable is found, the inline variable is replaced by its current value.

Along with the vl-string-subst function, you can use the vl-string-translate function to replace all instances of a character anywhere in a string with another character. Since the vl-string-translate function works with single characters, it provides much less control over using a text pattern that contains multiple characters.

The following example demonstrates how the vl-string-translate function can be used to replace all of the spaces in a string with underscores:

(vl-string-translate " " "_" "Project 123 - ABC")
"Project_123_-_ABC"

For more information on the vl-string-translate function, see the AutoCAD Help system.

Trimming a String

A string can be trimmed to a specific length by specifying a starting position and the number of characters to keep, resulting in what is known as a substring. The AutoLISP substr (short for substring) function allows you to keep a set of characters from a given string.

The following shows the syntax of the substr function:

(substr string start [length])

The arguments are as follows:

1. string The string argument represents the string that contains the substring you want to return.
2. Start The start argument represents the starting position in the string argument that the substring begins. A string starts at the first position.
3. Length The length argument represents the number of characters the substring should contain. The length argument is optional. If no argument is provided, the substring contains all of the characters from the starting position specified by the start argument to the end of the string.

The following are examples of the substr function and the values that are returned:

(substr "Programming is my hobby." 12)
" is my hobby."
(substr "Programming is my hobby." 1 11)
"Programming"
(substr "Programming is my hobby." 19 5)
"hobby"

Although the substr function is very helpful in pulling a string apart, it is not the most efficient function to use if you need to remove or trim specific characters from the left or right ends of a string. The AutoLISP vl-string-trim, vl-string-left-trim, and vl-string-right-trim functions are better suited to trimming specific characters, such as extra spaces or zeroes, from the ends of a string. The vl-string-trim function trims both ends of a string, whereas the vl-string-left-trim and vl-string-right-trim functions trim only the left and right ends of a string, respectively. Characters that are part of the character_set argument are trimmed from the respective ends of the string until a character that isn't a part of the character_set argument is encountered.

The following shows the syntax of the vl-string-trim, vl-string-left-trim, and vl-string-right-trim functions:

(vl-string-trim character_set string)
(vl-string-left-trim character_set string)
(vl-string-right-trim character_set string)

The arguments are as follows:

1. character_set The character_set argument represents the characters on the end or ends of the string specified by the string argument that should be trimmed off.
2. String The string argument represents the string that should be trimmed based on the characters specified by the character_set argument.

The following are examples of the vl-string-trim, vl-string-right-trim and vl-string-left-trim, functions and the values that are returned:

(vl-string-trim " " "  Extra spaces  ")
"Extra spaces"
(vl-string-right-trim " .0" "Trailing Zeroes and Spaces 0.10000   ")
"Trailing Zeroes and Spaces 0.1"
(vl-string-right-trim " .0" "Trailing Zeroes and Spaces 1.0000   ")
"Trailing Zeroes and Spaces 1"
(vl-string-left-trim " 0" "  001005 Leading Zeroes and Spaces")
"1005 Leading Zeroes and Spaces"