<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="VB6Parse Library Reference - ascb - String">
<title>ascb - String - VB6Parse Library Reference</title>
<link rel="stylesheet" href="../../../assets/css/style.css">
<link rel="stylesheet" href="../../../assets/css/docs-style.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
<script src="../../../assets/js/theme-switcher.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/vbnet.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<header class="docs-header">
<div class="container">
<h1><a href="../../../index.html">VB6Parse</a> / <a href="../../../library/index.html">Library</a> / <a href="../../../library/functions/string/index.html">String</a> / ascb</h1>
<p class="tagline">VB6 Library Reference</p>
</div>
</header>
<nav class="docs-nav">
<div class="container">
<a href="../../../index.html">Home</a>
<a href="../../../library/index.html">Library Reference</a>
<a href="../../../documentation.html">Documentation</a>
<a href="https://docs.rs/vb6parse" target="_blank">API Docs</a>
<a href="https://github.com/scriptandcompile/vb6parse" target="_blank">GitHub</a>
<button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
<span class="theme-icon">🌙</span>
</button>
</div>
</nav>
<main class="container">
<article class="library-item">
<h1 id="ascb-function">AscB Function</h1>
<p>Returns an <code>Integer</code> representing the byte value (ANSI code) of the first byte in a string.
The "B" suffix indicates this is the byte (ANSI) version of the <code>Asc</code> function.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">AscB(string)</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><strong>string</strong>: Required. Any valid string expression. If the string contains no characters,
a runtime error occurs (Error 5: Invalid procedure call or argument).</li>
</ul>
<h2 id="returns">Returns</h2>
<p>Returns an <code>Integer</code> (0-255) representing the byte value of the first byte in the string.</p>
<h2 id="remarks">Remarks</h2>
<ul>
<li><code>AscB</code> returns the ANSI byte value of the first byte in a string, not the character code.</li>
<li>The B suffix stands for "Byte", distinguishing it from the Unicode <code>AscW</code> function.</li>
<li>For single-byte character sets (ANSI), <code>AscB</code> and <code>Asc</code> return the same value.</li>
<li>For multi-byte character sets (like DBCS), <code>AscB</code> returns only the first byte of a multi-byte character.</li>
<li>The return value is always in the range 0-255.</li>
<li>If the string is empty (<code>""</code>), a runtime error occurs (Error 5).</li>
<li><code>AscB</code> is useful for low-level byte operations and working with binary data.</li>
<li>The inverse function is <code>ChrB</code>, which converts a byte value back to a character.</li>
<li>For Unicode code points, use <code>AscW</code> instead of <code>AscB</code>.</li>
</ul>
<h2 id="typical-uses">Typical Uses</h2>
<ol>
<li><strong>Byte-level text analysis</strong> - Examine individual bytes in ANSI strings</li>
<li><strong>Binary data processing</strong> - Extract byte values from binary strings</li>
<li><strong>File format parsing</strong> - Read byte values from file headers or data structures</li>
<li><strong>Legacy protocol support</strong> - Work with protocols that use ANSI byte values</li>
<li><strong>Character encoding detection</strong> - Analyze byte patterns in text</li>
<li><strong>Checksum calculations</strong> - Use byte values for checksums or hash calculations</li>
<li><strong>Low-level string comparison</strong> - Compare strings at the byte level</li>
</ol>
<h2 id="basic-examples">Basic Examples</h2>
<pre><code class="language-vbnet">' Example 1: Simple byte value
Dim byteVal As Integer
byteVal = AscB("A") ' Returns 65</code></pre>
<pre><code class="language-vbnet">' Example 2: Extended ANSI character
Dim code As Integer
code = AscB("é") ' Returns 233 (in Windows-1252 code page)</code></pre>
<pre><code class="language-vbnet">' Example 3: First byte of multi-byte character
' In DBCS (Double Byte Character Set) systems
Dim firstByte As Integer
firstByte = AscB("中") ' Returns first byte only (varies by encoding)</code></pre>
<pre><code class="language-vbnet">' Example 4: Control character
Dim tabByte As Integer
tabByte = AscB(vbTab) ' Returns 9</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<h3 id="validate-ascii-range">Validate ASCII Range</h3>
<pre><code class="language-vbnet">Function IsASCII(char As String) As Boolean
If Len(char) = 0 Then Exit Function
IsASCII = (AscB(char) < 128)
End Function</code></pre>
<h3 id="check-for-control-characters">Check for Control Characters</h3>
<pre><code class="language-vbnet">Function IsControlChar(char As String) As Boolean
If Len(char) = 0 Then Exit Function
Dim byteVal As Integer
byteVal = AscB(char)
IsControlChar = (byteVal < 32 Or byteVal = 127)
End Function</code></pre>
<h3 id="compare-byte-values">Compare Byte Values</h3>
<pre><code class="language-vbnet">Function CompareBytes(str1 As String, str2 As String) As Integer
If Len(str1) = 0 Or Len(str2) = 0 Then Exit Function
CompareBytes = AscB(str1) - AscB(str2)
End Function</code></pre>
<h3 id="extract-byte-array">Extract Byte Array</h3>
<pre><code class="language-vbnet">Function GetByteArray(text As String) As Variant
Dim bytes() As Integer
Dim i As Long
If Len(text) = 0 Then Exit Function
ReDim bytes(1 To Len(text))
For i = 1 To Len(text)
bytes(i) = AscB(Mid(text, i, 1))
Next i
GetByteArray = bytes
End Function</code></pre>
<h3 id="calculate-simple-checksum">Calculate Simple Checksum</h3>
<pre><code class="language-vbnet">Function SimpleChecksum(text As String) As Long
Dim i As Long
Dim checksum As Long
For i = 1 To Len(text)
checksum = checksum + AscB(Mid(text, i, 1))
Next i
SimpleChecksum = checksum Mod 256
End Function</code></pre>
<h3 id="detect-line-endings">Detect Line Endings</h3>
<pre><code class="language-vbnet">Function DetectLineEnding(text As String) As String
Dim i As Long
Dim byteVal As Integer
For i = 1 To Len(text)
byteVal = AscB(Mid(text, i, 1))
If byteVal = 13 Then ' CR
If i < Len(text) And AscB(Mid(text, i + 1, 1)) = 10 Then
DetectLineEnding = "CRLF"
Else
DetectLineEnding = "CR"
End If
Exit Function
ElseIf byteVal = 10 Then ' LF
DetectLineEnding = "LF"
Exit Function
End If
Next i
End Function</code></pre>
<h3 id="hex-dump-generator">Hex Dump Generator</h3>
<pre><code class="language-vbnet">Function ByteToHex(char As String) As String
If Len(char) = 0 Then Exit Function
Dim byteVal As Integer
byteVal = AscB(char)
ByteToHex = Right("0" & Hex(byteVal), 2)
End Function</code></pre>
<h3 id="case-insensitive-byte-compare">Case-Insensitive Byte Compare</h3>
<pre><code class="language-vbnet">Function ByteEqualsIgnoreCase(char1 As String, char2 As String) As Boolean
If Len(char1) = 0 Or Len(char2) = 0 Then Exit Function
Dim byte1 As Integer, byte2 As Integer
byte1 = AscB(char1)
byte2 = AscB(char2)
' Convert uppercase to lowercase (65-90 to 97-122)
If byte1 >= 65 And byte1 <= 90 Then byte1 = byte1 + 32
If byte2 >= 65 And byte2 <= 90 Then byte2 = byte2 + 32
ByteEqualsIgnoreCase = (byte1 = byte2)
End Function</code></pre>
<h3 id="filter-printable-characters">Filter Printable Characters</h3>
<pre><code class="language-vbnet">Function FilterPrintable(text As String) As String
Dim result As String
Dim i As Long
Dim byteVal As Integer
For i = 1 To Len(text)
byteVal = AscB(Mid(text, i, 1))
If byteVal >= 32 And byteVal <= 126 Then
result = result & Mid(text, i, 1)
End If
Next i
FilterPrintable = result
End Function</code></pre>
<h3 id="encode-for-url">Encode for URL</h3>
<pre><code class="language-vbnet">Function NeedsURLEncoding(char As String) As Boolean
If Len(char) = 0 Then Exit Function
Dim byteVal As Integer
byteVal = AscB(char)
' Check if character needs encoding
If (byteVal >= 48 And byteVal <= 57) Or _
(byteVal >= 65 And byteVal <= 90) Or _
(byteVal >= 97 And byteVal <= 122) Then
NeedsURLEncoding = False
Else
NeedsURLEncoding = True
End If
End Function</code></pre>
<h2 id="advanced-examples">Advanced Examples</h2>
<h3 id="binary-data-parser">Binary Data Parser</h3>
<pre><code class="language-vbnet">Function ParseBinaryHeader(data As String) As Variant
' Parse a binary file header (example: BMP format)
Dim header As Variant
ReDim header(1 To 4)
If Len(data) < 4 Then Exit Function
' Read signature bytes
header(1) = AscB(Mid(data, 1, 1)) ' 'B' = 66
header(2) = AscB(Mid(data, 2, 1)) ' 'M' = 77
' Read size bytes (little-endian)
header(3) = AscB(Mid(data, 3, 1))
header(4) = AscB(Mid(data, 4, 1))
ParseBinaryHeader = header
End Function</code></pre>
<h3 id="xor-encryptiondecryption">XOR Encryption/Decryption</h3>
<pre><code class="language-vbnet">Function XOREncrypt(text As String, key As String) As String
Dim result As String
Dim i As Long, keyPos As Long
Dim textByte As Integer, keyByte As Integer
If Len(text) = 0 Or Len(key) = 0 Then Exit Function
keyPos = 1
For i = 1 To Len(text)
textByte = AscB(Mid(text, i, 1))
keyByte = AscB(Mid(key, keyPos, 1))
result = result & ChrB(textByte Xor keyByte)
keyPos = keyPos + 1
If keyPos > Len(key) Then keyPos = 1
Next i
XOREncrypt = result
End Function</code></pre>
<h3 id="csv-field-parser-with-byte-analysis">CSV Field Parser with Byte Analysis</h3>
<pre><code class="language-vbnet">Function ParseCSVField(field As String) As String
Dim result As String
Dim i As Long
Dim byteVal As Integer
Dim inQuotes As Boolean
For i = 1 To Len(field)
byteVal = AscB(Mid(field, i, 1))
Select Case byteVal
Case 34 ' Double quote
inQuotes = Not inQuotes
Case 44 ' Comma
If Not inQuotes Then Exit Function
result = result & Chr(byteVal)
Case Else
result = result & Chr(byteVal)
End Select
Next i
ParseCSVField = result
End Function</code></pre>
<h3 id="character-set-validator">Character Set Validator</h3>
<pre><code class="language-vbnet">Function ValidateCharacterSet(text As String, validSet As String) As Boolean
Dim i As Long, j As Long
Dim textByte As Integer
Dim found As Boolean
For i = 1 To Len(text)
textByte = AscB(Mid(text, i, 1))
found = False
For j = 1 To Len(validSet)
If textByte = AscB(Mid(validSet, j, 1)) Then
found = True
Exit For
End If
Next j
If Not found Then
ValidateCharacterSet = False
Exit Function
End If
Next i
ValidateCharacterSet = True
End Function</code></pre>
<h2 id="error-handling">Error Handling</h2>
<pre><code class="language-vbnet">Function SafeAscB(text As String) As Integer
On Error GoTo ErrorHandler
If Len(text) = 0 Then
SafeAscB = -1 ' Error indicator
Exit Function
End If
SafeAscB = AscB(text)
Exit Function
ErrorHandler:
SafeAscB = -1
End Function</code></pre>
<h2 id="performance-notes">Performance Notes</h2>
<ul>
<li><code>AscB</code> is a very fast operation with minimal overhead</li>
<li>When processing long strings byte-by-byte, consider using <code>Mid</code> function efficiently</li>
<li>For repeated byte extraction, the performance is generally good</li>
<li>Avoid calling <code>AscB</code> in tight loops if the value can be cached</li>
<li><code>AscB</code> is faster than string comparison for byte-level operations</li>
</ul>
<h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>Validate input</strong> - Always check for empty strings before calling <code>AscB</code></li>
<li><strong>Use for byte operations</strong> - Prefer <code>AscB</code> over <code>Asc</code> when working with binary data</li>
<li><strong>Handle errors</strong> - Wrap <code>AscB</code> calls in error handlers when processing untrusted input</li>
<li><strong>Document byte values</strong> - Use constants or comments to explain non-obvious byte values</li>
<li><strong>Consider encoding</strong> - Be aware of system code page when working with extended ANSI</li>
<li><strong>Use with <code>ChrB</code></strong> - Pair with <code>ChrB</code> for byte-to-character conversions</li>
<li><strong>Test edge cases</strong> - Verify behavior with empty strings, control characters, and extended ANSI</li>
</ol>
<h2 id="comparison-with-related-functions">Comparison with Related Functions</h2>
<table>
<thead>
<tr>
<th>Function</th>
<th>Returns</th>
<th>Character Set</th>
<th>Use Case</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Asc</code></td>
<td>Integer (0-255 or Unicode)</td>
<td>System default</td>
<td>General character codes</td>
</tr>
<tr>
<td><code>AscB</code></td>
<td>Integer (0-255)</td>
<td>ANSI byte value</td>
<td>Byte-level operations</td>
</tr>
<tr>
<td><code>AscW</code></td>
<td>Integer (0-65535)</td>
<td>Unicode code point</td>
<td>International text</td>
</tr>
<tr>
<td><code>ChrB</code></td>
<td>String (ANSI)</td>
<td>ANSI (inverse)</td>
<td>Convert byte to character</td>
</tr>
</tbody>
</table>
<h2 id="common-byte-values-reference">Common Byte Values Reference</h2>
<p>Some commonly used byte values with <code>AscB</code>:
- <strong>0</strong>: Null character (NUL)
- <strong>9</strong>: Tab (HT)
- <strong>10</strong>: Line feed (LF)
- <strong>13</strong>: Carriage return (CR)
- <strong>32</strong>: Space
- <strong>48-57</strong>: Digits '0'-'9'
- <strong>65-90</strong>: Uppercase letters 'A'-'Z'
- <strong>97-122</strong>: Lowercase letters 'a'-'z'
- <strong>127</strong>: Delete (DEL)
- <strong>128-255</strong>: Extended ANSI (varies by code page)</p>
<h2 id="platform-notes">Platform Notes</h2>
<ul>
<li>On Windows systems, <code>AscB</code> uses the system's ANSI code page (e.g., Windows-1252)</li>
<li>Different code pages may interpret bytes 128-255 differently</li>
<li>For portable code, stick to ASCII range (0-127) when possible</li>
<li>On older systems (Windows 95/98/ME), ANSI encoding is the native string format</li>
<li>On modern Windows (NT-based), strings are Unicode internally but <code>AscB</code> still returns ANSI bytes</li>
</ul>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Returns only the first byte, not the full character in multi-byte encodings</li>
<li>Cannot handle Unicode characters outside the ANSI range (0-255) properly</li>
<li>Runtime error occurs with empty strings</li>
<li>Code page dependent for extended ANSI characters (128-255)</li>
<li>Not suitable for Unicode text processing (use <code>AscW</code> instead)</li>
</ul>
</article>
<div style="margin-top: 3rem; padding-top: 2rem; border-top: 1px solid var(--border-color);">
<p>
<a href="index.html">← Back to String</a> |
<a href="../index.html">View all functions</a>
</p>
</div>
</main>
<footer>
<div class="container">
<p>© 2024-2026 VB6Parse Contributors. Licensed under the MIT License.</p>
</div>
</footer>
</body>
</html>