= Strings and characters = 

Strings are immutable sequential collections of char objects that represent a text string.

In Cobra code these are typed as '''String'''  (on .Net this equates to System.String)
{{{
#!cobra
var name as String
def capitalize(title as String)
}}}
    
Within cobra you can catenate Strings explicitly with '+'
{{{
#!cobra
s1 = 'my' + 'string'  # after which s1 == "mystring"
}}}

Cobra also supports Python-style string slicing:
{{{
#!cobra
s = s[1:]  # chop off first char
s = s[:-1] # chop off last char
i = s.indexOf('foo')
if i <> -1
    s = s[:i]  # everything before 'foo'
}}}
Otherwise string manipulation is via the platform or Cobra runtime String and Char 
support methods.

An index into a string gives the position of a char object which may be the start point of 
a substring.

Chars are a representation of a single character (display glyph) in a string 
(for Unicode text a Unicode character) this is usually but may not necessarily be a single
Char for a single glyph (see Unicode and multibyte or wide chars)


== Literals ==

=== Char ===

Char literals are (usually) a single quoted character prefixed with a '''c'''.
{{{
#!cobra
ch = c'x'
}}}
Can be single or double quote delimited (usually single).

Cobra allows usual escape sequences for control characters
     \n, \r, \t, \0
{{{
#!cobra
nlch    = c'\n'  
tabch   = c'\t'
nulCh   = c'\0' 
}}}  

=== String ===
Literal Strings are (single) single quote or double quote delimited 
('string' or "another string")

All strings are single line (currently).

A [] delimited expression in a string indicates interpolation or substitution of enclosed 
expression at that point.
{{{
#!cobra
x='hops'
print 'hi [x]'  # outputs: hi hops
print "hi [x]"  # also outputs: hi hops

print 'Hi [customer.firstName] [customer.lastName]'
}}}
leading [ can be escaped '\[' to escape this substitution.


Literal strings support the usual escape characters.
    \n - newline.
    \r - carriage return.
    \t - tab.
    \0 - nul char.

(arbitrary embedded hex or unicode ??)

==== Raw Strings ====
    {{{r'string'}}} - unexpanded ('raw') string

Does not interpret escape chars or substitute expressions in []
    
==== non Substituted strings ====
    {{{ns'string[x]'}}} or {{{ns"string[x]"}}}

Does not do expression substitution - items in [] are treated as text

Interprets escape chars but suppresses expression interpolation/substitution
(handling of [])
    
== !DocStrings ==
Single or multiline """ delimited text intended to document the item. 

Terminating trigraph must be on new line (after initiating line) or (single line docstring ) at end on same as start line.

Allowed on File, (or after) class, struct, interface, var, def, sig, event, methods.
    Usual form
{{{
#!cobra
"""
Heres the doc string
"""
}}}
e.g.
{{{
#!cobra
class BigOne
    """
    Implementation of a BigOne thingy...
    yadda yadda yadda
    """

    var _initVal
        "The initial BigOne value"
}}}



== Platform ==

There is another string form to allow inline c# src code to be inserted at
the occurring position in generated source.

    {{{sharp"c# src code"}}}  or {{{sharp'c# src code'}}}  

e.g.
{{{
#!cobra
t = sharp'System.Type.GetType(qualifiedName)'
}}}
== Examples ==
{{{
#!cobra
s = 'A simple String'

i=10
ssub  = 'result is:[i]'    # ssub gets 'result is:10'

ns0 = ns'result is:[i]'    # ns   gets 'result is:[i]' 
ns1 =   'result is:\[i]'   # ns1  gets 'result is:[i]' 

rs = r'here [is]\nsome\r'  # rs gets string 'here [is]\nsome\r'
}}}
== Notes ==

Idiomatically most textstrings in cobra use single-quote ' as delimiters unless need to
enclose a '.

Exact String and Char representation is platform dependent as are support and utility [[BR]]
methods pending a complete portable Runtime library.[[BR]]
In the meantime we are using platform (.Net and Mono) capabilities and semantics. 

Eventually there will be support for multiline text strings (embedded newlines from source representation).