Strings

{anchor:top}
h1. {anchor:CHP-STRINGS} Strings
DTrace provides support for tracing and manipulating strings. This chapter describes the complete set of D language features for declaring and manipulating strings. Unlike ANSI-C, strings in D have their own built-in type and operator support so you can easily and unambiguously use them in your tracing programs.

[Top|#top]
h2. {anchor:CHP-STRINGS-1} String Representation
Strings are represented in DTrace as an array of characters terminated by a null byte (that is, a byte whose value is zero, usually written as {{'\0'}}). The visible part of the string is of variable length, depending on the location of the null byte, but DTrace stores each string in a fixed-size array so that each probe traces a consistent amount of data. Strings may not exceed the length of this predefined string limit, but the limit can be modified in your D program or on the {{dtrace}} command line by tuning the {{strsize}} option. Refer to [Chapter 16, Options and Tunables|Options and Tunables] for more information on tunable DTrace options. The default string limit is 256 bytes.\\
\\The D language provides an explicit {{string}} type rather than using the type {{char *}} to refer to strings. The {{string}} type is equivalent to a {{char *}} in that it is the address of a sequence of characters, but the D compiler and D functions like {{trace}} provide enhanced capabilities when applied to expressions of type {{string}}. For example, the string type removes the ambiguity of the type {{char *}} when you need to trace the actual bytes of a string. In the D statement:
{noformat}
trace(s);
{noformat}
if {{s}} is of type {{char *}}, DTrace will trace the value of the pointer {{s}} (that is, it will trace an integer address value). In the D statement:
{noformat}
trace(*s);
{noformat}
by definition of the {{*}} operator, the D compiler will dereference the pointer {{s}} and trace the single character at that location. These behaviors are essential to permitting you to manipulate character pointers that by design refer to either single characters, or to arrays of byte-sized integers that are not strings and do not end with a null byte. In the D statement:
{noformat}
trace(s);
{noformat}
if {{s}} is of type {{string}}, the {{string}} type indicates to the D compiler that you want DTrace to trace a null terminated string of characters whose address is stored in the variable {{s}}. You can also perform lexical comparison of expressions of type {{string}}, as described in [String Comparison|#CHP-STRINGS-5].

[Top|#top]

h2. {anchor:CHP-STRINGS-3} String Assignment
Unlike assignment of {{char *}} variables, strings are copied by value, not by reference. String assignment is performed using the {{=}} operator and copies the actual bytes of the string from the source operand up to and including the null byte to the variable on the left-hand side, which must be of type {{string}}. You can create a new variable of type {{string}} by assigning it an expression of type {{string}}. For example, the D statement:
{noformat}
s = "hello";
{noformat}
would create a new variable {{s}} of type {{string}} and copy the 6 bytes of the string {{"hello"}} into it (5 printable characters plus the null byte). String assignment is analogous to the C library function [{{strcpy}}(3C)|http://docs.sun.com/doc/819-2243/strcpy-3c?a=view], except that if the source string exceeds the limit of the storage of the destination string, the resulting string is automatically truncated at this limit.\\
\\You can also assign to a string variable an expression of a type that is compatible with strings. In this case, the D compiler automatically promotes the source expression to the string type and performs a string assignment. The D compiler permits any expression of type {{char *}} or of type {{char\[}}_n_{{\]}} (that is, a scalar array of {{char}} of any size), to be promoted to a {{string}}.

[Top|#top]
h2. {anchor:CHP-STRINGS-4} String Conversion
Expressions of other types may be explicitly converted to type {{string}} by using a cast expression or by applying the special {{stringof}} operator, which are equivalent in meaning:
{noformat}
s = (string) expression s = stringof ( expression )
{noformat}
The {{stringof}} operator binds very tightly to the operand on its right-hand side. Typically, parentheses are used to surround the expression for clarity, although they are not strictly necessary.\\
\\Any expression that is a scalar type such as a pointer or integer or a scalar array address may be converted to string. Expressions of other types such as {{void}} may not be converted to {{string}}. If you erroneously convert an invalid address to a string, the DTrace safety features will prevent you from damaging the system or DTrace, but you might end up tracing a sequence of undecipherable characters.

[Top|#top]
h2. {anchor:CHP-STRINGS-5} String Comparison
D overloads the binary relational operators and permits them to be used for string comparisons as well as integer comparisons. The relational operators perform string comparison whenever both operands are of type {{string}}, or when one operand is of type {{string}} and the other operand can be promoted to type {{string}}, as described in [String Assignment|CHP-STRINGS-3]. All of the relational operators can be used to compare strings:
h6. {anchor:TBL-STROPS} D Relational Operators for Strings
|{{<}}|left-hand operand is less than right-operand|
|{{<=}}|left-hand operand is less than or equal to right-hand operand|
|{{>}}|left-hand operand is greater than right-hand operand|
|{{>=}}|left-hand operand is greater than or equal to right-hand operand|
|{{==}}|left-hand operand is equal to right-hand operand|
|{{!=}}|left-hand operand is not equal to right-hand operand|
As with integers, each operator evaluates to a value of type {{int}} which is equal to one if the condition is true, or zero if it is false.\\
\\The relational operators compare the two input strings byte-by-byte, similar to the C library routine [{{strcmp}}(3C)|http://docs.sun.com/doc/819-2243/strcmp-3c?a=view]. Each byte is compared using its corresponding integer value in the ASCII character set, as shown in [{{ascii}}(5)|http://docs.sun.com/doc/819-2252/ascii-5?a=view], until a null byte is read or the maximum string length is reached. Some example D string comparisons and their results are:
|{{"coffee" < "espresso"}}|... returns 1 (true)|
|{{"coffee" == "coffee"}}|... returns 1 (true)|
|{{"coffee" >= "mocha"}}|... returns 0 (false)|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:28:11 PM{excerpt}