ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version

# String utility functions in Allegro CL

This document contains the following sections:

1.0 Operators in the util-string module

The util-string module is designed to contain operators which extend standard Common-Lisp string functionality in ways that are faster, more efficient, or more convenient.

Symbols in the util-string module are in the util.string package. You load the module with the form

    (require :util-string)

## 1.0 Operators in the util-string module

### string+

### Function

#### Package: util.string

Arguments: &rest objects

string+ returns a fresh simple string that contains the printed representation of all the individual objects passed as arguments in the order that they are supplied. Actual strings among objects are copied into the result string. Other objects are made into strings as if they were passed to princ-to-string (although the actual mechanism may be different for some types of objects), with `*print-pretty*` bound to `nil`. This function is designed to allow string to be used as identifiers or labels to be created quickly and efficiently.

### Treatment of NIL as an argument

string+ called with no arguments returns the null string "".

If any arguments are provided, all occurrances of `nil` are converted to the null string "", so this function acts as if the `nil` arguments were not provided at all. Symbols other than `nil` contribute their symbol name to the result string. If you want the symbol name of `nil` (i.e. "nil" in a modern lisp, "NIL" in an ANSI Lisp) in the result string, apply symbol-name to `nil` prior to passing the value to string+.

### string+ optimizations

The aim of string+ is to be much more efficient than `(format nil "..." ...)` and more flexible than cl:concatenate. string+ is highly optimized for the following types:

- strings
- symbols
- fixnums
- characters

You may not see the same speed or space efficiencies if other types of objects are included.

string+ is also optimized for smaller strings. Creating large strings will also not show much speed improvement over cl:format although it is easier to call.

### string+ and print variables

No action is taken by string+ to ensure that the values of the various print variables other than `*print-pretty*` (like, for example, `*print-array*`) are appropriate for providing information about the associated object in the string (see the example using `*print-array*`). If you want better control over how objects of types other than those listed above, such as arrays, floats (which are also affected by variables like `*read-default-float-format*`), lists, and so on, are included, consider passing the desired print representation as an argument rather than the object or using format in place of string+.

### Examples

    (use-package :util.string)
    (string+ 1 2 3 4 5) RETURNS "12345"
    (string+)  RETURNS ""
    (setq a "new string")
    (setq b (string+ a)) RETURNS "new string"
    (eq a b) RETURNS nil

    (string+ 1 #\space 2 #\- 3 "=" 4 :x 5) RETURNS "1 2-3=4x5"

    (let ((*print-base* 8))
      (string+ 16))
      RETURNS "20"  ;;  *print-base* etc. are respected

    ;; How more complex objects are stringified depends on things,
    ;; like print variables, which are not set by STRING+,
    ;; as this vector example shows:

    (setq my-vec (vector 1 2 3 4))
    (let ((*print-array* t))
      (string+ my-vec))
        RETURNS "#(1 2 3 4)"
    (let ((*print-array* nil))
      (string+ my-vec))
        RETURNS "#<Vector>"

    ;; Treatment of NIL as an argument (examples from a modern Lisp
    ;; so symbol names are case-sensitive). NIL is converted to the
    ;; null string while all other symbols are converted to their
    ;; SYMBOL-NAME.

    (string+) RETURNS ""
    (string+ nil) RETURNS ""
    (string+ "foo" nil 'bar) RETURNS "foobar"
    (string+ "foo" (symbol-name nil) 'bar nil)
       RETURNS "foonilbar"

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version