File Operations - Revision history

Dcurrent: /* String */

2026-08-24T05:44:45Z

String

← Older revision		Revision as of 01:44, 24 August 2026
Line 221:		Line 221:
	Result type names are case-insensitive.		Result type names are case-insensitive.

	=== String ===		==== String ====

	String parsing has two modes selected by the optional <code>decode_quotes</code> parameter. Legacy behavior remains the default so existing modules continue to work without modification. Quote-aware behavior is available by passing a nonzero fourth parameter.		String parsing has two modes selected by the optional <code>decode_quotes</code> parameter. Legacy behavior remains the default so existing modules continue to work without modification. Quote-aware behavior is available by passing a nonzero fourth parameter.

	String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages.		String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages.

	==== Legacy Parsing ====		===== Legacy Parsing =====

	Omitting <code>decode_quotes</code>, or passing <code>0</code>, uses legacy whitespace parsing:		Omitting <code>decode_quotes</code>, or passing <code>0</code>, uses legacy whitespace parsing:

Line 251:		Line 249:
	This behavior supports older scripts that read and reconstruct files one whitespace-delimited token at a time. Use <code>getfilestreamline()</code> instead when the complete line and its original formatting must be returned as one string.		This behavior supports older scripts that read and reconstruct files one whitespace-delimited token at a time. Use <code>getfilestreamline()</code> instead when the complete line and its original formatting must be returned as one string.

	==== Quote-Aware Parsing ====		===== Quote-Aware Parsing =====

	Pass a nonzero fourth parameter to enable modern quote-aware parsing:		Pass a nonzero fourth parameter to enable modern quote-aware parsing:

Line 270:		Line 267:
	Empty quoted arguments are supported. The maximum string length applies after quote delimiters are removed.		Empty quoted arguments are supported. The maximum string length applies after quote delimiters are removed.

	===== Double Quotes =====		====== Double Quotes ======

	Enclose multiple-word text in double quotes to group it as a single string.		Enclose multiple-word text in double quotes to group it as a single string.

Line 286:		Line 282:
	</pre>		</pre>

	===== Single Quotes =====		====== Single Quotes ======

	Single quotes may also group text:		Single quotes may also group text:

Line 302:		Line 297:
	</pre>		</pre>

	===== Mixed Quotes =====		====== Mixed Quotes ======

	The opposite quote type remains literal inside a quoted span:		The opposite quote type remains literal inside a quoted span:

Line 316:		Line 310:
	</pre>		</pre>

	=== Numeric ===		==== Numeric ====

	Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.		Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.

Dcurrent: /* Numeric */

2026-08-24T05:42:22Z

Numeric

← Older revision		Revision as of 01:42, 24 August 2026
Line 321:		Line 321:

	Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.		Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.

	~~=== Numeric ===~~
	~~Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.~~

	=== getfilestreamline() ===		=== getfilestreamline() ===

Dcurrent: /* String */

2026-08-24T05:41:08Z

String

← Older revision		Revision as of 01:41, 24 August 2026
Line 321:		Line 321:

	Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.		Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.

	~~=== String ===~~
	Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages. The limit applies after quote delimiters are removed.

	~~==== Double Quotes ====~~
	~~Enclose multiple word tokens in quotes to group as a single string.<syntaxhighlight lang="text">~~
	~~Value: "Hello world"~~

	~~Result: Hello world~~
	~~</syntaxhighlight>Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<syntaxhighlight lang="text">~~
	~~Value: prefix"two words"suffix~~

	~~Result: prefixtwo wordssuffix~~
	~~</syntaxhighlight>~~

	~~==== Single Quotes ====~~
	~~You may also enclose tokens with single quotes.<syntaxhighlight lang="text">~~
	~~Value: 'Its'~~

	~~Result: Its~~
	~~</syntaxhighlight>Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<syntaxhighlight lang="text">~~
	~~Value: It's~~

	~~Result: It's~~
	~~</syntaxhighlight>~~

	~~==== Mixed Quotes ====~~
	~~You may mix quote types to preserve quotations within the string. The opposite quote type remains literal inside a quoted span:<syntaxhighlight lang="text">~~
	~~Value: "Hello, it's a good day."~~

	~~Result: Hello, it's a good day.~~
	~~</syntaxhighlight><syntaxhighlight>~~
	~~Value: 'She said "hello".'~~

	~~Result: She said "hello".~~
	~~</syntaxhighlight>~~

	=== Numeric ===		=== Numeric ===

Dcurrent: /* getfilestreamargument() */

2026-08-24T05:40:17Z

getfilestreamargument()

Show changes

Dcurrent: /* getfilestreamargument() */

2026-08-24T05:30:58Z

getfilestreamargument()

← Older revision		Revision as of 01:30, 24 August 2026
Line 189:		Line 189:
	=== getfilestreamargument() ===		=== getfilestreamargument() ===

	<syntaxhighlight lang="c">		<syntaxhighlight lang="c" line="1">
	mixed result = getfilestreamargument(		mixed result = getfilestreamargument(
	filestream_handle,		filestream_handle,
Line 215:		Line 215:
	Existing three-parameter calls retain the historical behavior:		Existing three-parameter calls retain the historical behavior:

	<syntaxhighlight lang="c">		<syntaxhighlight lang="c" line="1">
	char value = getfilestreamargument(		char value = getfilestreamargument(
	filestream_handle,		filestream_handle,
Line 225:		Line 225:
	Pass a nonzero fourth parameter to request quote-aware parsing:		Pass a nonzero fourth parameter to request quote-aware parsing:

	<syntaxhighlight lang="c">		<syntaxhighlight lang="c" line="1">
	char value = getfilestreamargument(		char value = getfilestreamargument(
	filestream_handle,		filestream_handle,
Line 406:		Line 406:

	String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters. The limit applies to the value returned to the script.		String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters. The limit applies to the value returned to the script.

	~~<!-- Replace the existing getfilestreamargument() guidance bullets under Practical Guidance with the following. -->~~

	* Omit <code>decode_quotes</code> when compatibility with historical whitespace-token behavior is required.		* Omit <code>decode_quotes</code> when compatibility with historical whitespace-token behavior is required.
	* Pass <code>1</code> as the fourth <code>getfilestreamargument()</code> parameter when quoted fields should be treated as complete arguments.		* Pass <code>1</code> as the fourth <code>getfilestreamargument()</code> parameter when quoted fields should be treated as complete arguments.

Dcurrent: /* getfilestreamargument() */

2026-08-24T05:08:16Z

getfilestreamargument()

Show changes

Dcurrent: /* getfilestreamargument() */

2026-08-12T21:46:35Z

getfilestreamargument()

@@ Line 190: / Line 190: @@
 <syntaxhighlight lang="c">
 mixed result = getfilestreamargument( filestream_handle, argument_index, result_type);
-</syntaxhighlight>Reads an argument from the current line without advancing the read position. Argument indexes are zero-based and separated by spaces or tabs.
+</syntaxhighlight>Reads an argument beginning at the current file-stream position without advancing the position. Argument indexes are zero-based.
 {| class="wikitable"
 !<code>result_type</code>
@@ Line 209: / Line 211: @@
 The result type names are case-insensitive.
-Enclose text with quotes to form a single string argument. For example, <code>"Max Thunder"</code> or <code>"Hello world"</code>. Single quotes may appear within a double quote string, such as <code>"It's part of a sentence"</code>. The enclosing quotations themselves are discarded.
+=== String ===
 Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.

Dcurrent: /* getfilestreamargument() */

2026-08-12T04:35:35Z

getfilestreamargument()

← Older revision		Revision as of 00:35, 12 August 2026
Line 209:		Line 209:
	The result type names are case-insensitive.		The result type names are case-insensitive.

	~~Quoted~~ text ~~does not~~ form a single argument. For example, <code>"Max Thunder"</code> ~~still occupies two whitespace-separated argument indexes~~. ~~Use~~ <code>~~getfilestreamline()~~</code> ~~when a complete line must be preserved~~.		Enclose text with quotes to form a single string argument. For example, <code>"Max Thunder"</code> or <code>"Hello world"</code>. Single quotes may appear within a double quote string, such as <code>"It's part of a sentence"</code>. The enclosing quotations themselves are discarded.

	Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.		Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.

Dcurrent: /* Iterating Through Lines */

2026-07-24T17:13:04Z

Iterating Through Lines

Show changes

Dcurrent: Better byte explanation. Add character limit caution.

2026-07-24T17:02:26Z

Better byte explanation. Add character limit caution.

← Older revision		Revision as of 13:02, 24 July 2026
Line 333:		Line 333:

	== Binary Data ==		== Binary Data ==
	~~The API includes legacy <code>"~~byte~~"</code> modes~~ for ~~reading~~, ~~appending~~, and ~~saving~~. ~~These modes do~~ not ~~constitute~~ a ~~general~~-~~purpose binary~~ file interface.~~<blockquote>'''Caution:''' The current save implementation~~ determines the output length by scanning ~~the buffer as~~ a null~~-terminated string. A~~ byte value of <code>0</code> ~~therefore~~ ends the writable content, ~~and arbitrary binary data~~ cannot be ~~preserved~~ reliably. Use text ~~files unless the~~ native ~~byte implementation is revised to write the tracked buffer size directly~~.~~</blockquote>~~		Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.

			Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.

	== Practical Guidance ==		== Practical Guidance ==
Line 339:		Line 341:
	* Check every <code>openfilestream()</code> result for <code>-1</code>.		* Check every <code>openfilestream()</code> result for <code>-1</code>.
	* Keep handles private to the code that owns their lifecycle when practical.		* Keep handles private to the code that owns their lifecycle when practical.
			* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.
	* Save before closing when changes must persist.		* Save before closing when changes must persist.
	* Close every filestream when it is no longer needed.		* Close every filestream when it is no longer needed.