String Conversions

The functions acdbRToS() and acdbAngToS() convert values used in AutoCAD to string values that can be used in output or as textual data. The acdbRToS() function converts a real value, and acdbAngToS() converts an angle. The format of the result string is controlled by the value of AutoCAD system variables: the units and precision are specified by LUNITS and LUPREC for real (linear) values and by AUNITS and AUPREC for angular values. For both functions, the DIMZIN dimensioning variable controls how leading and trailing zeros are written to the result string. The complementary functions acdbDisToF() and acdbAngToF() convert strings back into real (distance) values or angles. If passed a string generated by acdbRToS() or acdbAngToS(), acdbDisToF() and acdbAngToF() (respectively) are guaranteed to return a valid value.

For example, the following fragment shows calls to acdbRToS(). (Error checking is not shown but should be included in applications.)

ads_real x = 17.5; 
char fmtval[12]; 
//Precision is the 3rd argument: 4 places in the first 
// call, 2 places in the others.
acdbRToS(x, 1, 4, fmtval); // Mode 1 = scientific 
acutPrintf("Value formatted as %s\n", fmtval); 
acdbRToS(x, 2, 2, fmtval); // Mode 2 = decimal 
acutPrintf("Value formatted as %s\n", fmtval); 
acdbRToS(x, 3, 2, fmtval); // Mode 3 = engineering 
acutPrintf("Value formatted as %s\n", fmtval); 
acdbRToS(x, 4, 2, fmtval); // Mode 4 = architectural 
acutPrintf("Value formatted as %s\n", fmtval); 
acdbRToS(x, 5, 2, fmtval); // Mode 5 = fractional 
acutPrintf("Value formatted as %s\n", fmtval);

These calls (assuming that the DIMZIN variable equals 0) display the following values on the AutoCAD text screen.

Value formatted as 1.7500E+01

Value formatted as 17.50

Value formatted as 1′-5.50″

Value formatted as 1′-5 1/2″

Value formatted as 17 1/2

When the UNITMODE system variable is set to 1, which specifies that units are displayed as entered, the string returned by acdbRToS() differs for engineering (mode equals 3), architectural (mode equals 4), and fractional (mode equals 5) units. For example, the first two lines of the preceding sample output would be the same, but the last three lines would appear as follows:

Value formatted as 1′5.50″

Value formatted as 1′5-1/2″

Value formatted as 17-1/2

The acdbDisToF() function complements acdbRToS(), so the following calls, which use the strings generated in the previous examples, all set result to the same value, 17.5. (Again, the examples do not show error checking.)

acdbDisToF("1.7500E+01", 1, &result); // 1 = scientific 
acdbDisToF("17.50", 2, &result); // 2 = decimal 
// Note the backslashes. Needed for inches.
acdbDisToF("1'-5.50\"", 3, &result); // 3 = engineering 
acdbDisToF("1'-5 1/2\"", 4, &result); // 4 = architectural 
acdbDisToF("17 1/2", 5, &result); // 5 = fractional

The following fragment shows calls to acdbAngToS() that are similar to the previous acdbRToS() examples.

ads_real ang = 3.14159; 
char fmtval[12]; 
// Precision is the 3rd argument: 0 places in the first
// call, 4 places in the next 3, 2 in the last.
acdbAngToS(ang, 0, 0, fmtval); // Mode 0 = degrees 
acutPrintf("Angle formatted as %s\n", fmtval); 
acdbAngToS(ang, 1, 4, fmtval); // Mode 1 = deg/min/sec 
acutPrintf("Angle formatted as %s\n", fmtval); 
acdbAngToS(ang, 2, 4, fmtval); // Mode 2 = grads 
acutPrintf("Angle formatted as %s\n", fmtval); 
acdbAngToS(ang, 3, 4, fmtval); // Mode 3 = radians 
acutPrintf("Angle formatted as %s\n", fmtval); 
acdbAngToS(ang, 4, 2, fmtval); // Mode 4 = surveyor's 
acutPrintf("Angle formatted as %s\n", fmtval);

These calls (still assuming that DIMZIN equals 0) display the following values on the AutoCAD text screen.

Angle formatted as 180

Angle formatted as 180d0′0″

Angle formatted as 200.0000g

Angle formatted as 3.1416r

Angle formatted as W

Note: The UNITMODE system variable also affects strings returned by acdbAngToS() when it returns a string in surveyor's units (mode equals 4). If UNITMODE equals 0, the string returned can include spaces (for example, “N 45d E”); if UNITMODE equals 1, the string contains no spaces (for example, “N45dE”).

The acdbAngToF() function complements acdbAngToS(), so the following calls all set the result argument to the same value, 3.14159. (This is rounded up to 3.1416 in the example that uses radians.)

acdbAngToF("180", 0, &result); // 0 = degrees  
acdbAngToF("180d0'0\"", 1, &result); // 1 = deg/min/sec 
acdbAngToF("200.0000g", 2, &result); // 2 = grads 
acdbAngToF("3.1416r", 3, &result); // 3 = radians 
acdbAngToF("W", 4, &result); // 4 = surveyor's
Note: When you have a string that specifies an angle in degrees, minutes, and seconds, you must use a backslash (\) to escape the seconds symbol (″) so that it doesn't appear to be the end of the string. The second of the preceding acdbAngToF() examples demonstrates this.
Parent topic: Conversions