[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]

String Handling

Concepts

Lisp strings in Creo Elements/Direct Modeling support the full range of Unicode characters. More precisely, the encoding used internally for strings and characters is UTF-16 (without Unicode surrogate support) Characters from any language covered by the Unicode standard can be used and even mixed within a single string. All the standard Common Lisp string handling functionality is available to process strings. Furthermore, there are APIs to convert strings and files between various encodings.

Versions of Creo Elements/Direct Modeling prior to OneSpace Modeling 2007 did not have Unicode support yet. In those versions, there was a distinction between extended strings which could contain multibyte characters as they are required particularly for East Asian languages, and standard Lisp strings, where each character was represented by a single byte. Extended strings could not be manipulated using the standard Lisp string functions. If you tried, usually you got an error message like this:

LISP error: "Foo" is not of type Lisp::SEQUENCE.

For full compatibility with all string types, both standard and extended, we recommended to use only the string functions described in this document. Those string functions were explicitly written to process both standard and extended strings.

With OneSpace Modeling 2007, the distinction between standard and extended strings disappears, and the restrictions for string handling have been lifted. Hence, you can now use any Common Lisp string function on any Creo Elements/Direct Modeling string! For documentation on Common Lisp, please consult the Common Lisp HyperSpec or a Common Lisp reference book, in particular the chapters on arrays, sequences and strings.

If your string processing code must run in versions before OneSpace Modeling 2007 and later, we recommend to use only the string functions documented here to ensure full compatiblity with older versions.

For background information on Unicode and advanced string processing, please consult the Unicode concepts documentation.

In the function descriptions in this document, a type specification of {STRING} refers to a string of any type (standard or extended).

Function Index Top of Page

Standard Lisp Functions

FORMAT  [function]

(format destination control-string [arguments])
Description:
For a full description, consult the Common Lisp HyperSpec or any Common Lisp reference book, such as:
Guy L. Steele, Jr.
Common Lisp - The Language - Second Edition
Digital Press
ISBN 1-55558-041-6

Parameters:
See Common Lisp documentation.

Return Value:
See Common Lisp documentation.

Example:
(setq part-height 33.75)
(setq a-string (format nil "Part ~S has a height of ~A~%"
                           (sd-inq-obj-basename (sd-inq-curr-part))
                           part-height))

Function Index Top of Page

LENGTH  [function]

(length sequence)
Description:
For a full description, consult the Common Lisp HyperSpec or any Common Lisp reference book, such as:
Guy L. Steele, Jr.
Common Lisp - The Language - Second Edition
Digital Press
ISBN 1-55558-041-6

Parameters:
See Common Lisp documentation.

Return Value:
See Common Lisp documentation.

Example:
(display (length "This is a string"))

Function Index Top of Page

OPEN  [function]

(OPEN filespec &key direction element-type if-exists if-does-not-exist external-format)
Description:
In OneSpace Modeling 2007 and later, (open) supports the :external-format keyword. Using this keyword, the encoding used in the input or output file can be specified. When reading data from an input file, the data will be converted from the specified encoding into the internal string encoding. Likewise, string data will be converted to the specified external format (encoding) when opening a file for output.

So for example, if you specify :utf-8 as the external format for a new file which is to be written, any data that you write to the file stream will be automatically converted into UTF-8.

There are two groups of supported encoding specifications, explicit and symbolic. Explicit specifications denote the actual encoding to be used, while symbolic specifications delegate the decision about the required encoding to Creo Elements/Direct Modeling.

The currently supported explicit encoding specifications are:

The currently supported symbolic encoding specifications are:

All the above symbolic encodings have in common that they do not cover the full range of Unicode characters, so when writing data from Creo Elements/Direct Modeling to a file, some data may be lost during the conversion.

The following table illustrates the differences between the above symbolic encodings:

Symbolic encoding Windows: English
Creo Elements/Direct Modeling: English
Windows: English
Creo Elements/Direct Modeling: Japanese
Windows: Japanese
Creo Elements/Direct Modeling: English
Windows: Japanese
Creo Elements/Direct Modeling: Japanese
:legacy HP-Roman8 Shift-JIS (codepage 932) HP-Roman8 Shift-JIS (CP932)
:locale ISO8859-1 (CP1252) Shift-JIS (CP932) ISO8859-1 (CP1252) Shift-JIS (CP932)
:system ISO8859-1 (CP1252) ISO8859-1 (CP1252) Shift-JIS (CP932) Shift-JIS (CP932)

The with-open-file macro also accepts an :external-format specification. For a full description of (open) and (with-open-file), consult the Common Lisp HyperSpec or any Common Lisp reference book, such as:

Guy L. Steele, Jr.
Common Lisp - The Language - Second Edition
Digital Press
ISBN 1-55558-041-6

Parameters:
See Common Lisp documentation.

Return Value:
See Common Lisp documentation.

Example:
  (let ((out (open "foobar_utf16.txt" :direction :output
                         :if-exists :supersede :if-does-not-exist :create
                   :external-format :utf-16)))
     (print "foobar" out)
     (close out))
                 
  (with-open-file (in "foobar_utf8.txt" :direction :input :external-format :utf-8)
           (display (read-line in nil nil)))

Function Index Top of Page

LOAD  [function]

(load filename)
Description:

Starting with OneSpace Modeling 2007, (load) supports the :external-format keyword which can be used to specify the encoding of the file which is to be loaded. For a list of encodings, see above. If no encoding is specified, (load) will try to detect the encoding of the file automatically:

For a full description, consult the Common Lisp HyperSpec or any Common Lisp reference book, such as:

Guy L. Steele, Jr.
Common Lisp - The Language - Second Edition
Digital Press
ISBN 1-55558-041-6

Parameters:
See Common Lisp documentation.

Return Value:
See Common Lisp documentation.

Example:
(load "foo.lsp" :external-format :iso8859-1)

Function Index Top of Page

Creo Elements/Direct Modeling specific functions

SD-STRING-P

(sd-string-p value)
Description:
Predicate to decide whether value is a string (either a normal Lisp string or an extended string).

Parameters:
value {Lisp object} - Value to check.

Return Value:
t - if value is a string or extended string
nil - otherwise

Example:
(sd-string-p "Foo")

Function Index Top of Page

SD-STRING=  [function]
SD-STRING<  [function]
SD-STRING>  [function]
SD-STRING<=  [function]
SD-STRING>=  [function]
SD-STRING/=  [function]

(sd-string= string-1 string-2)
(sd-string< string-1 string-2)
(sd-string> string-1 string-2)
(sd-string<= string-1 string-2)
(sd-string>= string-1 string-2)
(sd-string/= string-1 string-2)
Description:
These functions check whether string-1 is lexically string-2.

Parameters:
string-1 {STRING} - First string.
string-2 {STRING} - Second string.

Return Value:
t - if check for equality/inequality succeeded.
number {FIXNUM}
This non-nil value indicates that the check (except equality/inequality checks) is satisfied. The number indicates the first character position in string-2 where string-2 differs from string-1.
nil - check failed

Examples:
(sd-string= "Foo" "foo") => NIL
(sd-string< "Foo" "foo") => 0
(sd-string< "Part" "Party") => 4
(sd-string> "Foo" "foo") => NIL
(sd-string<= "A" "B") => 0
(sd-string<= "A" "Aa") => 1

Function Index Top of Page

SD-STRING-UPCASE  [function]
SD-STRING-DOWNCASE  [function]

(sd-string-upcase string)
(sd-string-downcase string)
Description:
Creates a new lowercase or uppercase string using the string string as source.

Parameters:
string {STRING} - Input string.

Return Value:
new-string - new lowercase or uppercase string

Examples:
(sd-string-upcase "HellO") => "HELLO"
(sd-string-downcase "Part1") => "part1"

Function Index Top of Page

SD-STRING-TRIM  [function]

(sd-string-trim string)
Description:
Trims leading and trailing spaces from string. Blank characters within the string are not removed.

Parameters:
string {STRING} - Input string.

Return Value:
new-string - string without leading and trailing spaces

Example:
(sd-string-trim "  Part 1   ") => "Part 1"

Function Index Top of Page

SD-STRING-SPLIT  [function]

(sd-string-split string delimiter)
Description:
Splits the given string at points where characters from the delimiter string are found. Delimiter characters are skipped in the output, which is a list of strings.

Parameters:
string {STRING} - Input string.
delimiter {STRING}
Sequence of characters which is used to split the input string.

Return Value:
strings {LIST of STRINGS} - List of string parts of the input string

Example:
(sd-string-split "A-long-string" "-") => ("A" "long" "string")

Function Index Top of Page

SD-STRING-REPLACE  [function]

(sd-string-replace string pattern replacement)
Description:
Returns a new string, where all occurrences of pattern in string are replaced with replacement.

Parameters:
string {STRING} - Input string.
pattern {STRING}
Pattern which is searched in string where each match will be replaced with replacement.
replacement {STRING} - the replacement string

Return Value:
string {STRING} - the new string with replaced portions

Example:
(sd-string-replace "/asmb1/asmb2/p1" "asmb" "a") => "/a1/a2/p1"

Function Index Top of Page

SD-NUM-TO-STRING  [function]

(sd-num-to-string number [digits])
Description:
Converts number to a string with a maximum number of digits after the decimal point. If the input number contains more digits after the decimal point than specified in digits, the resulting string will be rounded.

Parameters:
number {NUMBER} - Input number.
digits {FIXNUM [6]}
Maximum number of digits after the decimal point in the rounded result string. If number contains at least one digit after the decimal point and digits is set to 0, the result string will still have one digit after the decimal point.

Return Value:
string {STRING} - the converted number as string

Examples:
(sd-num-to-string 57.0) => "57"
(sd-num-to-string 52.1 0) => "52.1"
(sd-num-to-string 0.1234567) => "0.123457"
(sd-num-to-string 12345678901234567) => "1.234567890123457E+16"
(sd-num-to-string 47.0815 2) => "47.08"

Function Index Top of Page

SD-WRITE-TO-STRING  [function]

(sd-write-to-string any [digits])
Description:
Converts any Lisp object to a string. If the Lisp object is a number or a list containing numbers, the number of digits after the decimal point for those numbers in the resulting string is not more than given in the parameter digits. Symbols will be printed with their leading package qualifier.

Parameters:
any {Lisp object} - any Lisp object (number, string, symbol, keyword, list, ...) to be converted to a string
digits {FIXNUM [6]}
For numbers in any: Maximum number of digits after the decimal point in the rounded result string for those numbers.

Return Value:
string {STRING} - the converted Lisp object as string

Examples:
(sd-write-to-string 57.0) => "57"
(sd-write-to-string '(52.1 57.0)) => "(52.1 57)"
(sd-write-to-string '(:deg 0 15 30 45 90) => "(:deg 0 15 30 45 90)"
(sd-write-to-string 'sd-write-to-string)) => "oli::sd-write-to-string"

Function Index Top of Page

SD-READ-FROM-STRING  [function]

(sd-read-from-string string)
Description:
Same as the standard Lisp function read-from-string except that this function can handle empty strings or strings with just space characters.

Parameters:
string {STRING} - the string to be converted to a Lisp object

Return Value:
any {Lisp object} - the converted string
nil - the string could not be converted to a valid Lisp object

Examples:
(sd-read-from-string "57.0") => 57.0
(sd-read-from-string "(52.1 57)") => (list 52.1 57)

Function Index Top of Page

SD-STRING-MATCH-PATTERN-P  [function]

(sd-string-match-pattern-p pattern string
                           &optional :match-slash 
                                     :match-leading-period
                                     :match-backslash)
Description:
Returns T if string matches the specified pattern. The pattern can contain any number of wildcard characters or more complex regular expressions as defined for the UNIX fnmatch() function.
The optional additional three keywords give more specific pattern matching control. See below for a detailed explanation.

Parameters:
pattern {STRING}
A pattern which consists of regular characters, wildcard characters and more complex regular expressions as defined for the UNIX fnmatch() function.
string {STRING} - String which will be compared to pattern
:match-slash - optional parameter
If this keyword is given, a slash character ("/") in string must be explicitly matched by a slash in pattern; it cannot be matched by either the asterisk ("*") or question mark special character or by a bracket expression.
:match-leading-period - optional parameter
If this keyword is given, a leading period (".") must be explicitly matched. It will not be matched by a bracket expression, question mark or asterisk. A period is leading if it is the first character in string.
:match-backslash - optional parameter
If this keyword is given, a backslash character ("\") is treated as an ordinary character. If not given it escapes the following character. I.e. a backslash character in pattern followed by any other character matches that second character in string.

Return Value:
t - string matches pattern
nil - otherwise

Example:
(sd-string-match-pattern-p "[pP]art*" "Part4711") => T
(sd-string-match-pattern-p "[a-z]*" "012_part") => NIL
(sd-string-match-pattern-p "p?abc" "p23abc") => NIL
(sd-string-match-pattern-p "dir*file*" "dir_a/dir_b/filename") => T
(sd-string-match-pattern-p "dir*file*" "dir_a/dir_b/filename" :match-slash) => NIL

Function Index Top of Page

SD-MULTI-LANG-STRING  [function]

(sd-multi-lang-string default-string &optional language-pairs)
Description:
This function returns a string which corresponds to the language in which you run Creo Elements/Direct Modeling. If you run Creo Elements/Direct Modeling in a language which does not fit one of the optional language-pairs, this function returns default-string.

Use this function if you want to support more than one language with your add-on module. Wherever a string is expected, such as for a button title or prompt text of a dialog, use this function and Creo Elements/Direct Modeling picks the right localized string at runtime.

Note: In user/site/corp customization files like sd_avail_cmds.cmd or all toolbar/context menu definition files you must use the internal function (ui::multi-lang ...) which takes the same parameters as described here to achieve multi-language support within those files.

Note 2: If you run Creo Elements/Direct Modeling in a semi-supported language the keyword which matches the language string as passed to the $LANG or $SDLANG system variable can be used to define a multi-lang string in that semi-supported language.
Example: (sd-multi-lang-string "Text in English" :chinese_s "Text in simplified chinese")

Warning: sd-multi-lang-string will only work if the literal strings in the function call use a string encoding which matches the expectations of the Lisp reader.

If you load Lisp code from legacy-encoded files, the Lisp reader will assume by default that string literals in Lisp code are encoded according to the language which Creo Elements/Direct Modeling currently runs in. If you run Creo Elements/Direct Modeling in any of the supported Western languages (English, German, French etc.), and if you load the Lisp code from a non-Unicode file, all string literals in your code must be encoded in Roman8. If you run Creo Elements/Direct Modeling in Japanese, all string literals must be encoded according to Shift-JIS to be parsed properly, i.e. they can only contain Japanese and English characters, but no umlauts or accented characters.

If you mix SJIS- and Roman8-encoded string literals in a legacy-encoded file, chances are that the Lisp reader may report an error while your Lisp code is evaluated.

If you use sd-multi-lang-string in OneSpace Modeling 2007 and later, we recommend to encode the Lisp file which contains the function call either in UTF-8 or UTF-16, and to make sure that the file is marked with either a UTF-8 or UTF-16 byte-order mark (BOM). The Lisp reader will automatically detect the encoding when it finds the BOM, and will then process all literal strings in the file correctly (if, of course, they use either UTF-8 or UTF-16 encoding).

Parameters:
default-string {STRING}
Usually the English string. This string is used as fallback if you run Creo Elements/Direct Modeling in a language which no language-specific string is defined for.
language-pair {KEYWORD STRING pair}
This can be any number of the following keyword-value pairs:
  • :german - String in German, in Roman8 encoding (OneSpace Modeling 2006 and earlier) or UTF-8/UTF-16 encoding (OneSpace Modeling 2007 and later)
  • :french - String in French, in Roman8 encoding (OneSpace Modeling 2006 and earlier) or UTF-8/UTF-16 encoding (OneSpace Modeling 2007 and later)
  • :italian - String in Italian, in Roman8 encoding (OneSpace Modeling 2006 and earlier) or UTF-8/UTF-16 encoding (OneSpace Modeling 2007 and later)
  • :spanish - String in Spanish, in Roman8 encoding (OneSpace Modeling 2006 and earlier) or UTF-8/UTF-16 encoding (OneSpace Modeling 2007 and later)
  • :japanese - String in Japanese, in SJIS encoding (OneSpace Modeling 2006 and earlier) or UTF-8/UTF-16 encoding (OneSpace Modeling 2007 and later)

Return Value:
string {STRING} - the string in the current language

Examples:
(sd-multi-lang-string "Text in English" :german "Text in German")

   if language of Creo Elements/Direct Modeling is English: => "Text in English"
                                        German: => "Text in German"
                                        French: => "Text in English"
                                       Italian: => "Text in English"
                                       Spanish: => "Text in English"
                                      Japanese: => "Text in English"

(sd-multi-lang-string "Text in German" 
                      :french  "Text in French"
                      :italian "Text in Italian")

   if language of Creo Elements/Direct Modeling is English: => "Text in German"
                                        German: => "Text in German"
                                        French: => "Text in French"
                                       Italian: => "Text in Italian"
                                       Spanish: => "Text in German"
                                      Japanese: => "Text in German"

SD-STRING-TO-OCTETS  [function]
SD-OCTETS-TO-STRING  [function]

(sd-string-to-octets string :external-format encoding :calc-size calc-size)
(sd-octets-to-string array :external-format encoding)
Description:
String encoding conversions should usually be performed via the :external-format keyword in (open). However, in rare cases it may become necessary to convert string encodings in memory, i.e. without going through a file stream. This is what sd-string-to-octets and sd-octets-to-string are for.

sd-string-to-octets converts strings from the internally used encoding into the encoding specified via :external-format. The result is an array of integer values which represent the string in the specified encoding.

sd-octets-to-string converts from the specified external encoding into the internal encoding. It expects an array of integer values as its input, where the integer values represent a string in the specified encoding. The result is a string in Creo Elements/Direct Modeling's internal encoding.

Parameters:
string {STRING}
String in internal encoding
array {ARRAY}
Array of integer values which represent a string in the specified encoding.
encoding {KEYWORD}
Any of the supported encoding specifications - see the list of encodings supported by (open).
calc-size {t or nil}
sd-string-to-octets will return the length of the array if this parameter is set to t. The default value for this parameter is nil.

Return Value:
Array of integer values (sd-string-to-octets) or a string in internal encoding (sd-octets-to-string)
nil - if the conversion fails

Example:
  (oli:sd-octets-to-string 
    (oli:sd-string-to-octets "Mötley Crüe" :external-format :utf-8)
    :external-format :utf-8))

Function Index Top of Page

SD-RECODE-TEXTFILE  [function]

(sd-recode-textfile from-filename from-encoding to-filename to-encoding)
Description:
sd-recode-textfile converts a text file from its original encoding from-encoding to a new encoding to-encoding. All encodings which are documented for open can be used.

Parameters:
from-filename {STRING}
The filename of the text file to be converted.
from-encoding {KEYWORD}
A keyword specifying the encoding (see list of available encodings) of the input file.
to-filename {STRING}
The filename of the destination file.
to-encoding {KEYWORD}
A keyword specifying the encoding (see list of available encodings) of the destination file.

Return Value:
t - conversion successful
nil - conversion failed, input file could not be found, or output file could not be written.

Example:
  (oli:sd-recode-textfile "utf8.txt" :utf-8 "utf-16.txt" :utf-16)
[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]
© 2019 Parametric Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved