Name
STR

Syntax
STR (ausdruck,stellen,nachkommastellen)
oder
STR(formattext,ausdruck)

Aufklappen Wertebereiche
ausdruck beliebiger numerischer Ausdruck
stellen ≠ 0, Typ integer
0 ≤ nachkommastellen < |stellen|, Typ integer (2)
formattext = "%[flags][stellen][.nachkommastellen][einheit]", Typ Text (1)

––––––––––––––––
(1) Aufbau und Bestandteile von formattext:
%: Einleitendes Zeichen für nachfolgende Formatierungsanweisungen. Dieses Zeichen ist obligatorisch, alle anderen Bestandteile sind optional.

[flags] (für imperiale Einheiten/Bruchdarstellung):
  0: 0 Zoll werden dargestellt, sonst wird ein Leerstring ausgegeben.

[flags] (für metrische Einheiten/dezimal):
  #: Wenn ausdruck<1 Weglassen der Vorkommastellen (> DIN 1356) oder
  ^: Dezimaltrennzeichen nach amerikanischer (".") und nicht
      lokalisierter Notation (z.B. ",") (ab ArchiCAD® 8)
  -: Zahl im Ergebnistext links ausrichten (Standard: rechts)
  +: Positive Zahlen mit explizitem "+"-Vorzeichen
  [space]: Positive Zahlen mit explizitem Leerzeichen als Vorzeichen

[stellen] > 0 minimale Anzahl der Zeichen des Ergebnistextes

[nachkommastellen] ≥ 0 Anzahl der Dezimalstellen (Nachkomma)

[einheit] = Einheit, in die ausdruck umgerechnet wird:
(Ausgangseinheit ist (Quadrat-/Kubik-)Meter bzw. dezimale Altgrad.)
  ___Längenmaße:
  e: exponentiales Format (Meter)
  m: Meter
  mm: Millimeter
  cm: Zentimeter
  ffi: Fuß + Bruchzoll
  fdi: Fuß + dezimaler Zoll
  df: dezimaler Fuß
  fi: Bruchzoll
  di: dezimaler Zoll
  pt: Punkte (points); ab AC 13.0
  ___Flächenmaße:
  sqm: Quadratmeter
  sqcm: Quadratzentimeter
  sqmm: Quadratmillimeter
  sqf: Quadratfuß
  sqi: Quadratzoll
  ___Winkelmaße:
  dd: dezimale Grad
  dms: Grad, Minute, Sekunden
  gr: Neugrad
  rad: Bogenmaß
  surv: Vermessungseinheit
  ___Raummaße:
  cum: Kubikmeter
  l: Liter
  cucm: Kubikzentimeter
  cumm: Kubikmillimeter
  cuf: Kubikfuß
  cui: Kubikzoll
  cuy: Kubikyard
  gal: Gallone

––––––––––––––––
(2) |stellen| = ABS(stellen) (=Betrag von stellen)

Aufklappen Erläuterung
Wandelt einen numerischen ausdruck in einen Text um und gibt den Text als Ergebnis zurück.
STR() bildet somit das Gegenstück zu der SPLIT()-Funktion, mit der man einen Text in eine Zahl wandeln kann.

Es stehen 2 Syntaxformen zur Verfügung:

string = STR(ausdruck,stellen,nachkommastellen)
Gibt die resultierende, kaufmännisch gerundete Zahl aus ausdruck mit insgesamt mindestens |stellen| Zeichen insgesamt und mit nachkommastellen Stellen hinter dem Komma aus. Der Text kann auch breiter als |stellen| werden, wenn die Verteilung der Ziffern vor und hinter dem Komma es erfordern. Ist die Textbreite des reinen Zahlenergebnisses kleiner als |stellen|, wird führend (wenn stellen>0) oder nachfolgend (wenn stellen<0) mit Leerzeichen aufgefüllt. Negative Werte von ausdruck erhalten ein "-" als Vorzeichen, bei positiven Werten entfällt das "+". Es wird auch kein zusätzliches Leerzeichen vorangestellt. Bei der Bemessung der Breite werden Dezimalpunkt und ggf. Vorzeichen mitgezählt.
Siehe Beispiel 1.

string = STR(formattext,ausdruck)
Mit dieser 2. Variante kann das Ergebnis sehr detailliert, ähnlich wie in den Grundeinstellungen von ArchiCAD für Bemaßungen und Einheiten, formatiert werden. Ohne Berechnungsformel kann mit dieser Funktion auch in andere Einheiten umgewandelt werden. Siehe Wertebereich des Formatierungsstrings formattext. Ist formattext ein leerer Text, wird formattext="%#.3m" angenommen. Zu beachten ist, dass, auch wenn in formattext numerische Angaben gemacht werden (z.B. [stellen]), es sich um einen Text handelt. Der Formatstring kann auch als Variable übergeben werden, aber eben als zusammengesetzte Textvariable. Numerische Angaben müssen dann zunächst selbst erst in Text gewandelt werden.
Siehe Beispiel 2.

Aufklappen Beispiel
Beispiel 1 (nach 1. Syntaxschema):
string = STR(12.75,5,1) ! =» 12.8«
string = STR(12.75,5,2) ! =»12.75«
string = STR(12.75,5,4) ! =»12.7500«
string = STR(12.75,10,2) ! =»     12.75«


Beispiel 2 (nach 2. Syntaxschema):
zahl=12.75
string = STR("%#+9.1cm",zahl) ! = »  +1.275,0«

Der Wert von "zahl" (12.75) wird nach den Formatierungsregeln des vorangestellten Formatierungsstrings ("%#+9.1cm") umgewandelt. Dessen Zusammensetzung:
 "%" ist obligatorisch und ohne Wirkung.
 "#" Bei Zahlen kleiner 0 bewirkt das Weglassen des "0,"-Anteils. Hier, da 12.75>0 ist es ohne Wirkung.
 "+" Ausgabe des Pluszeichens, wenn der Wert von Zahl positiv ist.
 "9" Der Ergebnistext soll inkl. Vorzeichen und Punkt mind. 9 Zeichen breit sein. Fehlende Stellen werden vorne mit Leerzeichen gefüllt.
 ".1" Runden auf 1 Nachkommastelle.
 "cm" Umwandlung des Ergebnisses in Zentimeter, also zahl*100.

Beispiel 3:
zahl = 2.54
! Ausgabe in Metern, der internen Rechnungseinheit
string = STR("%.3m",zahl) ! = »2,540«
! Ausgabe in Zentimetern
string = STR("%.1cm",zahl) ! = »254,0«
! Ausgabe in Millimetern
string = STR("%.0mm",zahl) ! = »2.540«
! Ausgabe in Bruchzoll (1 Zoll=2,54 Zentimeter)
string = STR("%.2fi",zahl) ! = »100"«
! Ausgabe in dezimalen Zoll
string = STR("%.2di",zahl) ! = »100,00"«
! Ausgabe in dezimalen Fuß (1 Fuß=30,48 Zentimeter)
string = STR("%.4df",zahl) ! = »8,3333'«
! Ausgabe in Fuß und Bruchzoll
string = STR("%.2ffi",zahl) ! = »8'-4"«

Umrechnung in verschiedene Längeneinheiten.

Beispiel 4:
! Ausgabe in Quadratmetern (Standard)
string = STR("%.2sqm",1) ! = »1,00«
! Ausgabe in Quadratzentimetern
string = STR("%.0sqcm",1) ! = »10.000«
! Ausgabe in Quadratmillimetern
string = STR("%.0sqmm",1) ! = »1.000.000«
! Ausgabe in Quadratfuß
string = STR("%.4sqf",1) ! = »10,7639«
! Ausgabe in Quadratzoll
string = STR("%.0sqi",1) ! = »1.550«

Umrechnung in Flächeneinheiten. Zeichen für Zoll und Fuß werden nicht mit ausgegeben!

Beispiel 5:
zahl = 0.5
! Ausgabe in Kubikmeter (Standard)
string = STR("%.2cum",zahl) ! = »0,50«
! Ausgabe in Kubikzentimeter
string = STR("%.0cucm",zahl) ! = »500.000«
! Ausgabe in Kubikmillimeter
string = STR("%.0cumm",zahl) ! = »500.000.000«
! Ausgabe in Litern (Kubikdezimeter)
string = STR("%.0l",zahl) ! = »500«
! Ausgabe in Kubikyard
string = STR("%.4cuy",zahl) ! = »0,6540«
! Ausgabe in Kubikfuß
string = STR("%.4cuf",zahl) ! = »17,6573«
! Ausgabe in Kubikzoll
string = STR("%.1cui",zahl) ! = »30.511,9«
! Ausgabe in Galleonen
string = STR("%.1gal",zahl) ! = »132,1«

Umrechnung in Volumeneinheiten. Auch hier keine Ausgabe von Einheiten.

Beispiel 6:
winkel = 180   ! in Altgrad
! Ausgabe in Bogensekunden und Minuten.
string = STR("%7.4dms",winkel) ! = »180° 0' 0.00" «
! Neugrad mit 90 Altgrad=100 Neugrad
string = STR("%7.1gr",winkel) ! = » 200,0G «
! Ausgabe im Bogenmaß
string = STR("%7.4rad",winkel) ! = » 3,1416R « (=π)

Umrechnung von Winkelwerten. Hier werden die Einheiten mit ausgegeben.

Beispiel 7:
zahl=12.75
string = STR(“%-8”,zahl)   ! = »12,750  «
string = STR(“%8”,zahl)    ! = »  12,750«
string = STR(“%8.0”,zahl)  ! = »      13«
string = STR(“%-8.0”,zahl) ! = »13      «

Auffüllen mit Leerzeichen links (Standard) und rechts mit dem "-" - Flag.

Beispiel 8:
string = STR(“%.4”,0.1815) ! = »0,1815«
string = STR("%.2”,0.1815) ! = »0,18«
string = STR("%.3”,0.1815) ! = »0,182«

Kaufmännisches Runden bei Angabe der Nachkommastellen.

Beispiel 9:
string = STR("%.2",12.75)   ! = »12,75«
string = STR("%+.2",12.75)  ! = »+12,75«
string = STR("% .2",12.75)  ! = » 12,75«
string = STR("% .2",-12.75) ! = »-12,75«

Ausgabe des Vorzeichens "-" immer, wenn negativ; "+" bzw. " " nur mit gesetzten Flags.

Beispiel 10:
string = STR("%.2",0.75)  ! = »0,75«
string = STR("%#.2",0.75) ! = »75«
string = STR("%#.4",0.75) ! = »7.500«

Zahlen zwischen 0 und 1 können auf reine Nachkommadarstellung (nach DIN 1356) umgestellt werden. Die Anzahl der Nachkommastellen haben einen Einfluß auf die Darstellung.

Beispiel 11:
string = STR("%10.2",12.75)  ! = » 1.275,00«
string = STR("%^10.2",12.75) ! = » 1275.00«

Ab ArchiCAD 9 kann die Zahl unabhängig von der lokalisierten ArchiCAD-Version in die amerikanische/internationale Notation ohne Tausendertrennung und Punkt statt Dezimalkomma gewandelt werden.

Beispiel 12:
string = STR("%",0)  ! = »0,000«
string = STR("%˜",0) ! = »0«

Tja, das Tilde-Flag ab AC8. Wofür ist es wirklich? oder funktioniert es nur in STR{2}()?

Beispiel 13:
zoll = 4,8768
string = STR("%.4",zoll)    ! = »4,8768«
string = STR("%ffi",zoll)   ! = »16'«
string = STR("%0ffi",zoll)  ! = »16'-0"«
string = STR("%fdi",zoll)   ! = »16'«
string = STR("%0fdi",zoll)  ! = »16'-0.00"«
string = STR("%0.3fdi",zoll) ! = »16'-0.000"«
string = STR("%fi",0)  ! = »0"«
string = STR("%0fi",0) ! = »0"«
string = STR("%df",0)  ! = »0,00'«
string = STR("%0df",0) ! = »0,00'«

Auch bei der Bruchzolldarstellung können 0-Darstellungen unterdrückt werden.


Beispiel 14:
zahl=5.08
string = STR("%10.1df",zahl) ! = »      16,7'«
string = STR("%10.1di",zahl) ! = »     200,0"«
string = STR("%10.1fi",zahl) ! = »200"«
string = STR("%10.1fdi",zahl) ! = »16'-8.0"«
string = STR("%10.1ffi",zahl) ! = »16'-8"«
string = STR("%-10.1di",zahl) ! = »200,0"«

Fehlerhaftes Auffüllen mit Leerzeichen auf die Minimalbreite des Ergebnistextes bei der Ausgabe im imperialen Format (Bruchzoll).

Beispiel 15:
winkel=180
string = STR("%-10.1",winkel)   ! = »180,0     «
string = STR("%10.1dd",winkel)  ! = »     180,0° «
string = STR("%-10.1dd",winkel) ! = »180,0     ° «

Unlogisches Auffüllen mit Leerzeichen bei Winkelmaßen.

Aufklappen Besonderheiten
1. In beiden Syntaxschemen ist im Textergebnis das Dezimaltrennzeichen in der landesüblichen Notation, im deutschen ArchiCAD also ein Komma. Damit kann keine direkte Rückwandlung in eine Zahl mit SPLIT() erfolgen, da diese Funktion, die, wie in der übrigen GDL-Syntax üblich, die amerikanische Notation erwartet. Man muss zuvor dem Text die landesspezfischen Zeichen (auch den in Deutschland üblichen Tausender-Trennpunkt) z.B. mit STRSUB() entziehen bzw. umwandeln.

Workaround:
s = STRSTR(ergebnis,",")
IF s THEN
 vor = STRSUB(ergebnis,1,s-1)
 nach = STRSUB(ergebnis,s+1,STRLEN(ergebnis)-s)
 ergebnis = vor + "." + nach
 ENDIF


2. Die Nutzung einstellbarer Rundungsintervalle in den Grundeinstellungen der Zeichnungstexte wird ab ArchiCAD 8 von der REQUEST()-Funktion ebenfalls zurückgegeben. Diese Funktionalität ("*"-Flag, siehe STR{2}()-Funktion) ist aber mit der STR-Funktion nicht möglich. Ältere Objekte können daher an diesem Punkt "scheitern" und einen Fehler verursachen. In diesen Objekten ist die STR()- mit der STR{2}()-Funktion zu ersetzen.

3. Die Rundungsfunktionalität der STR{2}()-Funktion wurde wohl wegen der nötigen Rückgabe eines 2. Strings nicht in die STR()-Funktion integriert. In ArchiCAD 9 sind die Rundungsoptionen noch einmal erweitert. Diese Erweiterungen wirken sich aber nur auf den 1. Ergebnisstring aus und benötigen keinen zusätzlichen. Deswegen funktionieren diese Flags ("*5" und "*6") (natürlich ab ArchiCAD 9) auch in der STR()-Funktion. Von deren bewußten Verwendung raten wir aber ab, da dieses Feature nicht dokumentiert und in künftigen Versionen wieder zurückgenommen werden könnte.

4.Die Angabe von Einheiten dient im Wesentlichen der Umrechnung. Die Einheitsbezeichner werden nur bei Bruchzahlen (inch/Zoll) und bei Winkelangaben ausgegeben. Aus welchem Grund auch immer wird bei den Winkelmaßen zusätzlich immer noch ein Leerzeichen angehängt. Siehe Beispiel 15.

5. Bei den Einheiten mit Bruchzoll (fi,fdi,ffi,di) funktioniert die Angabe der Mindestbreite (stellen) nicht erwartungsgemäß. Siehe Beispiel 14.

Aufklappen Tipps und Tricks
Mit der REQUEST()-Funktion lassen sich die Ausgabeformate der Zeichnungstexte (Maßketten, Winkelmaße etc.) als Formatierungsstrings gleicher Syntax abrufen und direkt in der STR()-Funktion verwenden. Siehe z.B. Abruf Format Maßkettentexte.

GDL-Talk (members):
Some interesting precisions (EN)
Archi-Talk:
Code for fraction of inches (EN)

Aufklappen ArchiCAD
ab 5.0