String Handling

• Concepts

• Standard Lisp functions
  • format
  • length
  • open
  • load

• Creo Elements/Direct Modeling specific string functions
  • sd-string-p
  • sd-string=
  • sd-string<
  • sd-string>
  • sd-string<=
  • sd-string>=
  • sd-string/=
  • sd-string-upcase
  • sd-string-downcase
  • sd-string-trim
  • sd-string-split
  • sd-string-replace
  • sd-num-to-string
  • sd-write-to-string
  • sd-read-from-string
  • sd-string-match-pattern-p
  • sd-multi-lang-string
  • sd-string-to-octets
  • sd-octets-to-string
  • sd-recode-textfile

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).

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))

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"))

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:

• :roman8 - use HP-Roman8 encoding, as it was used in OneSpace Modeling 2006 and earlier versions when running a Western European version of Creo Elements/Direct Modeling. HP-Roman8 does not cover the full range of Unicode characters, so when writing data to a file, some data may be lost during the conversion.
• :cp932 - use Shift-JIS encoding as defined by Microsoft code page 932; this is the encoding which was used in OneSpace Modeling 2006 and earlier versions when running Creo Elements/Direct Modeling in Japanese. Shift-JIS does not cover the full range of Unicode characters, so when writing data to a file, some data may be lost during the conversion.
• :iso8859-1 - use ISO8859-1 encoding. ISO8859-1 does not cover the full range of Unicode characters, so when writing data to a file, some data may be lost during the conversion.
• :utf-8 - use UTF-8 encoding for input and output. UTF-8 covers the full range of the Unicode character set, so no character data will be lost during the conversion.
• :utf-8-bom - same as UTF-8, but when writing a new file using this encoding, a special marker (called the "UTF-8 BOM") will be written as the first three bytes of the file. This marker will help editors and other tools to automatically detect the encoding used in the file. Some file types, however, should not use BOMs; for example, neither HTML nor XML files use a BOM, even if their content happens to be encoded in UTF-8. When opening a stream for input, :utf-8 and :utf-8-bom will behave in the same way, i.e. they detect and skip the BOM automatically.
• :utf-16 - use UTF-16LE (little endian) encoding. When writing files in this encoding, a BOM ("byte-order marker") is always written, i.e. they start with a UTF-16LE BOM. UTF-16 covers the full range of the Unicode character set, so no character data will be lost during the conversion.

The currently supported symbolic encoding specifications are:

• :legacy - this is the encoding which the older, non-Unicode versions of Creo Elements/Direct Modeling (OneSpace Modeling 2006 and earlier) would use in a given locale. For instance, when running a Japanese version of OneSpace Modeling 2005, it assumes that all strings are encoded according to Shift-JIS (:cp932, see above), and when running a German version of OneSpace Modeling 2002, it will think that the default string encoding is Roman8 (:roman8, see above).

  Most useful for communicating with older versions of Creo Elements/Direct Modeling or Creo Elements/Direct Drafting. This is also the implicit default encoding if you don't specify an :external-format explicitly.

• :system - this is the encoding which the operating system chooses by default for non-Unicode applications. On Western European versions of Windows, this is an encoding known as "codepage 1252" (sometimes also referred to as "ANSI" or "ISO8859-1"). On Japanese systems, the default Windows encoding is Shift-JIS (or, more precisely, codepage 932).

  Most useful when communicating with external non-Unicode components and applications.

• :locale - Like :system, but the choice of encoding depends on the language in which Creo Elements/Direct Modeling currently runs rather than the operating system's language. When running Creo Elements/Direct Modeling in a Western European language or in English, :locale evaluates to "codepage 1252" (which is mostly equivalent to ISO8859-1, see above), even if Creo Elements/Direct Modeling runs on a Japanese or Chinese operating system.

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)))

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:

• If the file starts with a UTF-8 BOM, :utf-8 is assumed.
• If the file starts with a UTF-16 BOM, :utf-16 is assumed.
• Otherwise, :legacy encoding is assumed.

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)

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")

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

• equal to
• less than
• greater than
• less than or equal to
• greater than or equal to
• not equal to

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

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"

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"

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")

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"

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"

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"

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)

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

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))

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)