Libraries

Getting Started

Tidal supports two types of libraries:

• Embedded Libraries: Built into the compiler. (Ship with the Compiled Tidal Library, no External Files Needed.)
  • Example:

    import(math, embedded);
    print(math.sqrt(16));
    

• External Libraries: Custom .tdx files in your project directory.
  • Example:

    import(mylib, external);
    print(mylib.function());
    

Syntax

To Import Libraries, just use import():

import(math);

If you have a external library named lib.tdx, you can import it in the same way:

import(lib);

But, if your external library is called math.tdx, and you import it in the way mentioned above, the Embedded math.rs will get loaded, not your custom library. To Fix this, you can explictly define the import:

import(math, external);

import(math, embedded);

This will ensure that you are importing the right library.

Run Functions

To Run Functions using the Above Syntax, You will need to first specify the library name, followed by the function.

Example:

import(math, embedded);

print(math.PI);

The only exception to this is, the std() library, because that will be added to the global scope, and does not need to be prepended by the library name. You cannot prepend it, or else it will give an error.

Embedded Library List

Standard Library

The std library is automatically imported in every Tidal program. No explicit import needed.
Check out the inbuilt functions in this library in the Built In Functions Page.

Math Library

Import using:

import(math);

Or Explictly

import(math, embedded);

Constants

• PI: 3.14159...
• E: 2.71828...
• TAU: 6.28318...
• INF: Infinity

Functions

• abs(x): Absolute value
• pow(x, y): x raised to power y
• sqrt(x): Square root
• sin(x): Sine function
• cos(x): Cosine function
• tan(x): Tangent function
• log(x): Natural logarithm
• ln(x): Natural logarithm (alias)
• gcd(x, y): Greatest Common Divisor
• sqrt(x): Square Root
• ceil(x)
• floor(x)
• round(x)

System Library

Import using:

import(sys);

Or explicitly:

import(sys, embedded);

Constants

• PLATFORM: Current platform ("windows", "linux", "darwin", or "unknown")
• ARGV: Command line arguments array
• EXECUTABLE: Path to current executable
• VERSION: Tidal version
• PATH_SEP: Platform-specific path separator
• MAXSIZE: Maximum integer size
• OS_NAME: Operating system name
• ARCH: System architecture
• PATH: System PATH as array

Functions

Process Functions:

• exit(code): Exit program with status code
• getpid(): Get current process ID

Environment Functions:

• getenv(name): Get environment variable value
• setenv(name, value): Set environment variable
• unsetenv(name): Remove environment variable

Path Functions:

• getcwd(): Get current working directory
• abspath(path): Get absolute path

Platform Functions:

• getloadavg(): Get system load averages (Unix only)
• getsizeof(obj): Get approximate size of object

OS Library

Import using:

import(os);

Or explicitly:

import(os, embedded);

Constants

• name: Operating system name ("nt" for Windows, "posix" for Unix)
• linesep: System line separator ("\r\n" for Windows, "\n" for Unix)

Functions

File Operations:

• makedirs(path): Create directory and all parent directories
• removedirs(path): Remove directory and its empty parent directories
• rename(src, dst): Rename file or directory
• remove(path): Remove a file
• listdir(path?): List directory contents (defaults to current directory)
• chdir(path): Change current working directory
• exists(path): Check if path exists
• isfile(path): Check if path is a file
• isdir(path): Check if path is a directory
• system(cmd): Execute system command, returns exit code

IO Library

Import using:

import(io);

Or explicitly:

import(io, embedded);

Functions

File Operations:

• open(path, mode): Open file with specified mode:
  • "r": Read only
  • "w": Write only (creates/truncates)
  • "w+": Read and write (creates/truncates)
  • "a": Append only (creates)
  • "a+": Read and append (creates)
• write(path, content): Write content to a file (overwrites existing content)
• read(path): Read entire file content as string
• append(path, content): Append content to end of file
• exists(path): Check if file exists at path
• remove(path): Delete file at path
• rename(old_path, new_path): Rename/move file from old path to new path

Memory Library

Import using:

import(mem);

Or explicitly:

import(mem, embedded);

Constants

• POINTER_SIZE: Size of a pointer in bytes
• MAX_INT: Maximum integer value
• MIN_INT: Minimum integer value
• ALIGNMENT_MAX: Maximum memory alignment
• WORD_SIZE: System word size in bytes
• CACHE_LINE: CPU cache line size (64 bytes)
• PAGE_SIZE: Memory page size (4096 bytes)

Functions

Memory Inspection:

• sizeof(obj): Get raw size of object in bytes
• getsizeof(obj): Get total size including overhead
• getalign(obj): Get memory alignment of object
• id(obj): Get memory address of object
• getrefcount(obj): Get reference count of object
• allocated(): Get memory allocation statistics as [total_allocated, total_blocks]

Memory Analysis:

• meminfo(arr): Get array memory info as [length, capacity, total_bytes, ref_count]
• fraginfo(arr): Get array fragmentation info as [wasted_slots, fragmentation_percentage]
• memrange(arr): Get array memory address range as [start_addr, end_addr]
• memdiff(obj1, obj2): Get memory distance between objects
• isshared(obj): Check if object has multiple references
• sharemem(arr1, arr2): Check if arrays share same memory

Memory Management:

• deepcopy(obj): Create deep copy of object
• shrink(arr): Shrink array capacity to fit current size
• reserve(arr, n): Pre-allocate array capacity for n additional elements
• is(obj1, obj2): Check if objects are same instance

Creating External Libraries

• Create a file with .tdx extension
• Define functions:

  func example(x) {
  return x * 2; 
  }
  

• Import into your .td program:

  import(yourLibrary);
  

  OR

  import(yourLibrary, external);
  

• Done! Use the Functions in your code!

Creating an Embedded Library

Please Check Out the Libraries Secion in the Developers Page.