diff --git a/uppsrc/Core/srcdoc.tpp/CoreTutorial$en-us.tpp b/uppsrc/Core/srcdoc.tpp/CoreTutorial$en-us.tpp index ee523e270..5bd1c733a 100644 --- a/uppsrc/Core/srcdoc.tpp/CoreTutorial$en-us.tpp +++ b/uppsrc/Core/srcdoc.tpp/CoreTutorial$en-us.tpp @@ -2,7 +2,7 @@ topic "U++ Core value types tutorial"; [2 $$0,0#00000000000000000000000000000000:Default] [l288;i1120;a17;O9;~~~.1408;2 $$1,0#10431211400427159095818037425705:param] [a83;*R6 $$2,5#31310162474203024125188417583966:caption] -[b83;*4 $$3,5#07864147445237544204411237157677:title] +[H4;b83;*4 $$3,5#07864147445237544204411237157677:title] [i288;O9;C2 $$4,6#40027414424643823182269349404212:item] [b42;a42;ph2 $$5,5#45413000475342174754091244180557:text] [l288;b17;a17;2 $$6,6#27521748481378242620020725143825:desc] @@ -28,23 +28,23 @@ topic "U++ Core value types tutorial"; Content of String can be also obtained in form zero terminated const char `*ptr (valid till the next mutating operation only.&] [s5; You can assign a C string literal to String&] -[s7; &] +[s5; &] [s7; String a;&] [s7; a `= `"Hello`";&] [s7; &] [s16; a `= Hello&] [s7; &] -[s7; &] +[s5; &] [s5; concatenate with another String or literal&] -[s7; &] +[s5; &] [s7; a `= a `+ `" world`";&] [s7; &] [s16; a `= Hello world&] [s7; &] -[s7; &] +[s5; &] [s5; or single character or specified number of characters from another String or literal&] -[s7; &] +[s5; &] [s7; a.Cat(`'!`');&] [s7; &] [s16; a `= Hello world!&] @@ -53,37 +53,34 @@ String or literal&] [s7; &] [s16; a `= Hello world!ABC&] [s7; &] -[s7; &] +[s5; &] [s5; Clear method empties the String&] -[s7; &] +[s5; &] [s7; a.Clear();&] -[s7; &] -[s7; &] +[s5; &] [s5; You can use operator<< to append to existing String. Note that this is more efficient form than operator`+ as String is not required to be assigned a temporary. Also, U`+`+ provides extensible framework for converting values to String&] -[s7; &] +[s5; &] [s7; for(int i `= 0; i < 10; i`+`+)&] [s7; -|a << i << `", `";&] [s7; &] [s16; a `= 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, &] -[s16; &] -[s16; &] +[s5; &] [s5; Sometimes is is useful to use operator<< to produce a temporary String value (e.g. as real argument to function call).&] -[s16; &] +[s5; &] [s7; String().Cat() << `"Number is `" << 123 << `".`"&] -[s7; &] +[s5; &] [s5; Note: This strange special Cat method is needed because C`+`+ does not allow non`-cont references to temporary objects.&] -[s7; &] +[s5; &] [s16; Number is 123.&] -[s7; &] -[s7; &] +[s5; &] [s5; String provides methods for obtaining character count, inserting characters into String or removing them&] -[s7; &] +[s5; &] [s7; a `= `"0123456789`";&] [s7; &] [s16; a.GetLength() `= 10&] @@ -96,9 +93,9 @@ characters into String or removing them&] [s7; &] [s16; a `= 01456789&] [s7; &] -[s7; &] +[s5; &] [s5; as well as a couple of searching and comparing methods&] -[s7; &] +[s5; &] [s7; a.Find(`'e`')&] [s7; &] [s16; a.Find(`'e`') `= 8&] @@ -118,11 +115,10 @@ characters into String or removing them&] [s7; a.Find(`"ted`")&] [s7; &] [s16; a.Find(`"ted`") `= 10&] -[s7; &] -[s7; &] +[s5; &] [s5; You can get slice of String using Mid method; with single parameter it provides slice to the end of String&] -[s7; &] +[s5; &] [s7; a.Mid(3, 3)&] [s7; &] [s16; a.Mid(3, 3) `= 56789&] -[s7; &] -[s7; &] +[s5; &] [s5; You can also decrease the length of String using Trim&] -[s7; &] +[s5; &] [s7; a.Trim(4);&] [s7; &] [s16; a `= 0145&] -[s7; &] -[s7; &] +[s5; &] [s5; You can obtain int values of individual characters using operator`[`]&] -[s7; &] +[s5; &] [s7; a`[0`]&] [s7; &] [s16; a`[0`] `= 48&] -[s7; &] -[s7; &] +[s5; &] [s5; or the value of first character using operator`* (note that if GetLengt() `=`= 0, this will return zero terminator)&] -[s7; &] +[s5; &] [s7; -|DUMP(`*a);&] [s7; &] [s16; `*a `= 48&] -[s7; &] -[s0; &] +[s5; &] [s3; 2. StringBuffer&] [s5; If you need a direct write access to String`'s C`-string character buffer, you can use complementary StringBuffer class. One of reasons to do so is when you have to deal with some C`-API functions&] +[s5; &] [s7; void CApiFunction(char `*c)&] [s7; `{&] [s7; -|strcpy(c, `"Hello`");&] @@ -172,7 +165,7 @@ reasons to do so is when you have to deal with some C`-API functions&] [s7; -|String x [* `=] b;&] [s7; &] [s16; x `= Hello&] -[s7; &] +[s5; &] [s5; In this case, SetLength creates a C array of 200 characters. You can then call C`-API function. Later you set the real length using Strlen `- this function performs strlen of buffer and sets @@ -182,12 +175,13 @@ clears the StringBuffer content (operation is fast and does not depend on the number of characters).&] [s5; Another usage scenario of StringBuffer is about altering existing String&] +[s5; &] [s7; -|b `= x;&] [s7; -|b`[1`] `= `'a`';&] [s7; -|x `= b;&] [s7; &] [s16; x `= Hallo&] -[s16; &] +[s5; &] [s5; Similar to assigning StringBuffer to String, assigning String to StringBuffer clears the source String.&] [s5; StringBuffer also provides appending operations:&] @@ -208,7 +202,7 @@ of interface methods. U`+`+ also provides conversions between String and WString and you can also use 8 bit string literals with WString. Conversion is ruled by current [*/ default character set][/ . ]Default value of default character set is CHARSET`_UTF8.&] -[s7; &] +[s5; &] [s7; -|WString x `= `"characters 280`-300: `";&] [s7; -|for(int i `= 280; i < 300; i`+`+)&] [s7; -|-|x.Cat(i);&] @@ -225,76 +219,76 @@ set][/ . ]Default value of default character set is CHARSET`_UTF8.&] [s7; &] [s16; x `= characters 280`-300: ĘęĚěĜĝĞğĠġĢģĤĥĦħĨĩĪī (appended)-|&] -[s7; &] +[s5; &] [s5; [/ (Note: y content is displayed as result of conversion from utf`-8 encoded data)]&] [s5; &] [s3; 4. Date and Time&] [s5; To represent date and time, U`+`+ provides Date and Time concrete types.&] -[s7; &] +[s5; &] [s7; -|Date date `= GetSysDate();&] [s0; &] [s16; date `= 01/21/2007&] -[s0; &] -[s0; All data members of Date structure are public:&] -[s0; &] +[s5; &] +[s5; All data members of Date structure are public:&] +[s5; &] [s16; date.year `= 2007&] [s16; date.month `= 1&] [s16; date.day `= 21&] -[s0; &] -[s0; Dates can be compared:&] -[s0; &] +[s5; &] +[s5; Dates can be compared:&] +[s5; &] [s16; date > Date(1970, 1, 1) `= true&] -[s0; &] -[s0; Adding a number to Date adds a number of days to it:&] -[s0; &] +[s5; &] +[s5; Adding a number to Date adds a number of days to it:&] +[s5; &] [s16; date `+ 1 `= 01/22/2007&] -[s0; &] -[s0; Subtraction of dates yields a number of days between them:&] -[s0; &] +[s5; &] +[s5; Subtraction of dates yields a number of days between them:&] +[s5; &] [s16; date `- Date(1970, 1, 1) `= 13534&] -[s0; &] -[s0; U`+`+ defines the beginning and the end of era, most algorithms +[s5; &] +[s5; U`+`+ defines the beginning and the end of era, most algorithms can safely assume that as minimal and maximal values Date can represent:&] [s0; &] [s16; Date`::Low() `= 01/01/`-4000&] [s16; Date`::High() `= 01/01/4000&] [s0; -|&] -[s0; &] -[s0; Time is [/ derived] from Date, adding members to represent time:&] -[s0; &] +[s5; &] +[s5; Time is [/ derived] from Date, adding members to represent time:&] +[s5; &] [s7; -|Time time `= GetSysTime();&] -[s0; &] +[s5; &] [s16; time `= 01/21/2007 23:28:59&] [s16; (Date`&)time `= 01/21/2007&] [s16; (int)time.hour `= 23&] [s16; (int)time.minute `= 28&] [s16; (int)time.second `= 59&] -[s0; &] -[s0; Times can be compared:&] -[s0; &] +[s5; &] +[s5; Times can be compared:&] +[s5; &] [s16; time > Time(1970, 0, 0) `= true&] -[s0; &] -[s0; Warning: As Time is derived from the Date, most operations automatically +[s5; &] +[s5; Warning: As Time is derived from the Date, most operations automatically convert Time back to Date. You have to use ToTime conversion function to convert Date to Time:&] -[s0; &] +[s5; &] [s16; time > date `= false&] [s16; time > ToTime(date) `= true&] [s16; &] -[s0; &] -[s0; Like Date, Time supports add and subtract operations, but numbers +[s5; &] +[s5; Like Date, Time supports add and subtract operations, but numbers represent seconds (using int64 datatype):&] -[s0; &] +[s5; &] [s16; time `+ 1 `= 01/21/2007 23:29:00&] [s16; time `+ 24 `* 3600 `= 01/22/2007 23:28:59&] [s16; time `- date `= 0&] [s16; time `- ToTime(date) `= 84539&] -[s0; &] -[s0; Time also defines era limits:&] -[s0; &] +[s5; &] +[s5; Time also defines era limits:&] +[s5; &] [s16; Time`::Low() `= 01/01/`-4000 00:00:00&] [s16; Time`::High() `= 01/01/4000 00:00:00&] [s5;/ &] @@ -303,7 +297,7 @@ represent seconds (using int64 datatype):&] converting values to default textual form.&] [s5; System is based on the combination of template functions [/ (following code is part of U`+`+ headers)]:&] -[s7; &] +[s5; &] [s7; template &] [s7; inline String AsString(const T`& x)&] [s7; `{&] @@ -323,14 +317,13 @@ code is part of U`+`+ headers)]:&] [s7; -|s.Cat(AsString(x));&] [s7; -|return s;&] [s7; `}&] -[s7; &] -[s7; &] +[s5; &] [s5; Client types have to either define String [*/ ToString] method (usually more convenient) or specialize [*/ AsString] template. Such types can be appended to Streams or Strings using [*/ operator<<]. Of course, U`+`+ value types and primitive types have required items predefined by U`+`+:&] -[s7; &] +[s5; &] [s7; -|FileOut fout(ConfigFile(`"test.txt`"));&] [s7; -|String sout;&] [s7; -|&] @@ -338,10 +331,9 @@ items predefined by U`+`+:&] [s7; -|sout << 1.23 << `' `' << GetSysDate() << `' `' << GetSysTime();&] [s7; &] [s16; sout `= 1.23 01/22/2007 01/22/2007 17:58:58&] -[s0; &] +[s5; &] [s5; Getting client types involved into this schema is not too difficult (example shows both methods):&] -[s7; &] [s7; struct BinFoo `{&] [s7; -|int x;&] [s7; -|&] @@ -372,15 +364,15 @@ items predefined by U`+`+:&] [s3; 6. Value&] [s5; U`+`+ provides one special value type, Value, that can be used to store and retrieve other values.&] -[s7; &] +[s5; &] [s7; -|Value a `= 1;&] [s7; -|Value b `= 2.34;&] [s7; -|Value c `= GetSysDate();&] [s7; -|Value d `= `"hello`";&] -[s7; &] +[s5; &] [s5; Usually, value types define typecast operator to Value and constructor from Value, so that interaction is for the most part seamless:&] -[s7; &] +[s5; &] [s7; -|int x `= a;&] [s7; -|double y `= b;&] [s7; -|Date z `= c;&] @@ -390,14 +382,13 @@ from Value, so that interaction is for the most part seamless:&] [s16; y `= 2.34&] [s16; z `= 01/24/2007&] [s16; s `= hello&] -[s0; &] -[s0; As for primitive types, Value seamlessly works with [* int], [* int64], +[s5; &] +[s5; As for primitive types, Value seamlessly works with [* int], [* int64], [* bool] and [* double].&] -[s0; &] -[s0; Casting Value to a type that it does not contain causes runtime +[s5; Casting Value to a type that it does not contain causes runtime error. On the other hand, conversion between related types is possible:&] -[s0; &] +[s5; &] [s7; &] [s7; -|double i `= a;&] [s7; -|int j `= b;&] @@ -408,21 +399,21 @@ possible:&] [s16; j `= 2&] [s16; k `= 01/24/2007&] [s16; t `= hello&] -[s0; &] -[s0; To determine type of value stored in Value, you can use [* Is] +[s5; &] +[s5; To determine type of value stored in Value, you can use [* Is] method:&] -[s0; &] +[s5; &] [s16; a.Is() `= true&] [s16; a.Is() `= false&] [s16; b.Is() `= true&] [s16; c.Is() `= false&] [s16; c.Is() `= true&] [s16; d.Is() `= true&] -[s0; &] -[s0; Note that Is tests for absolute type match, not for compatible +[s5; &] +[s5; Note that Is tests for absolute type match, not for compatible types. For that reason, for widely used compatible types utility functions are defined:&] -[s0; &] +[s5; &] [s16; &] [s16; IsNumber(a) `= true&] [s16; IsNumber(b) `= true&] @@ -436,7 +427,7 @@ primitive types double, int and int64 (defined as lowest number the type can represent). If type supports ordering (<, >), all values of the type are greater than Null value. To test whether a value is empty, use IsNull function.&] -[s7; &] +[s5; &] [s7; -|int x `= Null;&] [s7; -|int y `= 120;&] [s7; -|Date d `= Null;&] @@ -447,19 +438,18 @@ a value is empty, use IsNull function.&] [s16; IsNull(d) `= true&] [s16; e > d `= true&] [s0; &] -[s0; C`+`+ language note: Null is the only instance of Nuller type. +[s5; C`+`+ language note: Null is the only instance of Nuller type. Assigning Null to primitive types is achieved by cast operators of Nuller, other types can do it using constructor from Nuller.&] -[s0; &] -[s0; As a special case, if Value contains Null, it is convertible +[s5; As a special case, if Value contains Null, it is convertible to any value type that can contain Null:&] -[s0; &] +[s5; &] [s7; &] [s7; -|Value v `= x;&] [s7; -|e `= v;&] [s7; &] [s16; IsNull(e) `= true&] -[s0; &] +[s5; &] [s5; Function Nvl is U`+`+ analog of well known SQL function coalesce (ifnull, Nvl), which returns the first non`-null argument (or Null if all are Null).&] @@ -469,19 +459,20 @@ Null if all are Null).&] [s7; -|int c `= 1;&] [s7; &] [s16; Nvl(a, b, c) `= 123&] -[s0; &] +[s5; &] [s3; 8. Client types and Value, RawValue, RichValue&] [s5; There are two Value compatibility levels. The simple one, [*/ RawValue], has little requirements for the type used `- only copy constructor and assignment operator are required:&] -[s7; &] +[s5; &] [s7; struct RawFoo `{&] [s7; -|String x;&] [s7; `};&] [s7; &] -[s7; &] -[s0; (int this case, default copy constructor and assignment operator +[s5; &] +[s5; (int this case, default copy constructor and assignment operator are provided by compiler).&] +[s5; &] [s7; &] [s7; -|RawFoo h;&] [s7; -|h.x `= `"hello`";&] @@ -490,14 +481,13 @@ are provided by compiler).&] [s16; q.Is() `= true&] [s16; q.To().x `= `"hello`"&] [s7; &] -[s0; [*/ RichValue] level Values provide more operations for Value -`- equality test, IsNull test, hashing, conversion to text and -serialization. In order to make serialization work, type must -also have assigned an integer id (client types should use ids -in range 10000..20000). Type can provide the support for these -operations via template function specializations or (perhaps -more convenient) using defined methods and inheriting from ValueType -base class template:&] +[s5; [* RichValue] level Values provide more operations for Value `- +equality test, IsNull test, hashing, conversion to text and serialization. +In order to make serialization work, type must also have assigned +an integer id (client types should use ids in range 10000..20000). +Type can provide the support for these operations via template +function specializations or (perhaps more convenient) using defined +methods and inheriting from ValueType base class template:&] [s7; &] [s7; struct Foo : ValueType `{&] [s7; -|int x;&] @@ -531,10 +521,10 @@ base class template:&] [s7; -|LoadFromString(v, s);&] [s7; &] [s16; v.Get() `= 54321&] -[s0; &] -[s0; To avoid RichToValue and ValueTo calls, the client type can +[s5; &] +[s5; To avoid RichToValue and ValueTo calls, the client type can also provide constructor from Value and cast operator to Value:&] -[s0; &] +[s5; &] [s7; struct Foo : ValueType `{&] [s7; -|int x;&] [s7; -|&] @@ -565,7 +555,7 @@ combines them to provide final hash value for composite type:&] b); `}&] [s7; `};&] [s7; &] -[s0; Note that GetHashValue is defined as function template that +[s5; Note that GetHashValue is defined as function template that calls GetHashValue method of its argument, therefore defining GetHashValue method defines GetHashValue function too.&] [s7; &] @@ -578,5 +568,9 @@ GetHashValue method defines GetHashValue function too.&] [s7; -|x.a << `'!`';&] [s7; &] [s16; GetHashValue(x) `= 3378606405&] -[s7; &] -[s0;/ ]] \ No newline at end of file +[s5; &] +[s3; Recommended tutorials:&] +[s5; If you want to learn more, we have several tutorials that you +can find useful:&] +[s5;l160;i150;O0;~~~32; [^topic`:`/`/CtrlLib`/srcdoc`/Tutorial`$en`-us^ GUI +tutorial] `- learn about creating GUI application with U`+`+.]] \ No newline at end of file