Core Function StrNew

From Sputnik Wiki
(Difference between revisions)
Jump to: navigation, search
(→Description)
(→Example)
 
(3 intermediate revisions by one user not shown)
Line 1: Line 1:
 
<pre>
 
<pre>
−
StrNew( <char>, <length>, <flag>
+
StrNew( <char>, <length> )
 
</pre>
 
</pre>
  
 
=== Description ===
 
=== Description ===
  
−
Create a new string of a given length filled with a given char (or optionally return it as a CharPtr rather than a new string.
+
Create a new string of a given length filled with a given char.
  
 
=== Parameters ===
 
=== Parameters ===
Line 11: Line 11:
 
==== char ====
 
==== char ====
  
 +
What char should populate the new string.
  
 
==== length ====
 
==== length ====
  
−
==== flag ====
+
How big the new string should be.
−
Optional; Choose if you want to return as a normal string or a CharPtr
+
−
 
+
−
true -- Return as CharPtr
+
−
 
+
−
false -- Return as string
+
−
 
+
−
Default: false
+
  
 
=== Return Value ===
 
=== Return Value ===
  
−
Success: If the flag is TRUE then return will be a CharPtr. If the flag is FALSE then return will be a normal string
+
Success: The new string.
  
 
Failure: null
 
Failure: null
Line 31: Line 25:
 
=== Remarks ===
 
=== Remarks ===
  
−
If the FLAG is true memory will be allocated and the pointer returned to the memory you must use Free() command to reclaim that memory after you are finished with it, You can of course convert it to a string using (string) cast then immediately free the CharPtr.
+
None.
−
 
+
−
One benefit of this function is it will create the String/CharPtr in the correct memory size and type that Sputnik uses for Strings (should be in UTF8 format so 2 bytes per char with a zero terminator 2 bytes long).
+
  
 
=== Example ===
 
=== Example ===
  
 
Normal string
 
Normal string
 +
 
<syntaxhighlight lang="sputnik">
 
<syntaxhighlight lang="sputnik">
 
$Str = StrNew('T', 15);
 
$Str = StrNew('T', 15);
 
$Str[0] = 'A'; // Set first char to A
 
$Str[0] = 'A'; // Set first char to A
−
$Str[1] = 'A'; // Set second char to B
+
$Str[1] = 'B'; // Set second char to B
 
echo $Str; // Prints: ABTTTTTTTTTTTTT
 
echo $Str; // Prints: ABTTTTTTTTTTTTT
 
// Of course you could just make the string like
 
// Of course you could just make the string like
Line 47: Line 40:
 
// OR
 
// OR
 
// $Str = "AB" . ('T' x 13);
 
// $Str = "AB" . ('T' x 13);
−
// The purpose of this function is just to make it more
 
−
// simple to create a string for use in Fixed() and (char*) etc
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Example of TRUE flag and converting the return to string once done with it
+
You can create a string full of null terminators since Sputnik strings use a *length* property so a string can contain nulls etc (of course there is an actual null terminator at the end of the length) this means when you use StrNew() to create a string with say 100 length and all null terminators then the string will be 100 chars in size.
 +
 
 +
However you might want to eventually cut the string into the size you want it to be once you finish editing it to do that we can use TrimToNull() which will trim the string to first NULL it finds.
 +
 
 
<syntaxhighlight lang="sputnik">
 
<syntaxhighlight lang="sputnik">
−
// Create pointer to a newly created string containing '5' chars of 'A'
+
$Str = StrNew(@'\0', 15);
−
// the return will be as a CharPtr rather than a normal string
+
$Str[0] = 'A'; // Set first char to A
−
$PTR = StrNew('A', 5, true);
+
$Str[1] = 'B'; // Set second char to B
−
*$PTR = 'T'; // Set first character to T
+
say $Str; // Prints: AB
−
$PTR[1] = 'B'; // Set second character to B
+
say StrLen($Str); // 15
−
$STR = (string)$PTR; // Convert the CharPtr to a string
+
 
−
free($PTR); // Free the CharPtr as it is no longer needed
+
// Lets fix the string so its no longer 15 in size
−
printr( $STR ); // Prints TBAAA
+
// but fits all way to null term so 2 in size
 +
say "Trimming...";
 +
$Str = TrimToNull($Str);
 +
say $Str; // Prints: AB
 +
say StrLen($Str); // 2
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
[[Category:Core Function]]
 
[[Category:Core Function]]

Latest revision as of 10:09, 19 September 2015

StrNew( <char>, <length> )

Contents

Description

Create a new string of a given length filled with a given char.

Parameters

char

What char should populate the new string.

length

How big the new string should be.

Return Value

Success: The new string.

Failure: null

Remarks

None.

Example

Normal string 

$Str = StrNew('T', 15);
$Str[0] = 'A'; // Set first char to A
$Str[1] = 'B'; // Set second char to B
echo $Str; // Prints: ABTTTTTTTTTTTTT
// Of course you could just make the string like
// $Str = "ABTTTTTTTTTTTTT";
// OR
// $Str = "AB" . ('T' x 13);

You can create a string full of null terminators since Sputnik strings use a *length* property so a string can contain nulls etc (of course there is an actual null terminator at the end of the length) this means when you use StrNew() to create a string with say 100 length and all null terminators then the string will be 100 chars in size.

However you might want to eventually cut the string into the size you want it to be once you finish editing it to do that we can use TrimToNull() which will trim the string to first NULL it finds. 

$Str = StrNew(@'\0', 15);
$Str[0] = 'A'; // Set first char to A
$Str[1] = 'B'; // Set second char to B
say $Str; // Prints: AB
say StrLen($Str); // 15
 
// Lets fix the string so its no longer 15 in size
// but fits all way to null term so 2 in size
say "Trimming...";
$Str = TrimToNull($Str);
say $Str; // Prints: AB
say StrLen($Str); // 2
Retrieved from "http://ubersoft.org/Sputnik/wiki/index.php/Core_Function_StrNew"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox