Why use the HCL?
-
The HCL was designed to function the same in both javascript and php. This elimates the need to remember how to do the same thing in two different languages.
-
The function prototypes also allows for self-documentation. For example:
Determine if variable $i is a positive integer
Language |
If Statement |
JAVASCRIPT |
if( typeof $i == 'Number' && $i % 2 == 0 && $i >= 0 ) { ... } |
PHP |
if( gettype($i) == 'integer' && $i >= 0 ) { ... } |
HCL ( JAVASCRIPT & PHP )
|
if( is_positive_integer_($i) ) { ... } |
What the HCL isn't.
-
The most comprehensive and advanced algorithms available. It is designed to be lightweight, not the end all and be all of computer libraries.
-
The most efficient library on Earth. Some of the source code designs are not the most efficient way to do things for various reasons. Whenever possible the HCL is made as efficent as possible, but some functions are slightly more inefficent than they could be in order to prevent code redundency and to ensure the functions work the same on both Javascript and PHP.
-
The fastest way to do things. The HCL is designed to be used in basic web and server situations. It was not designed to scale to anything that has to run millions of times per second.
-
Designed to be compatible with Windows in any way. While most of the code should be compatible, the HCL was written in Linux for standard Javascript and generic php. It isn't tested against windows browsers or php running on Microsoft servers.
-
A library that has been designed to be compatible with ANY Microsoft browser.
HCL Prototypes
The function prototypes are one of the reasons that spurred the development of the HCL. The prototypes has been designed to remove confusion and to"self document" by making it crystal clear what each function does.
-
All core functions and classes have identical prototypes between Javascript and PHP, so there is never a need to look up a prototype for one language or another.
-
All hcl functions end in a "_" to avoid conflicts between other functions.
-
Whenever possible, full words are used to describe function names and arguments.
-
Often there are 2 versions of a function that is usually a single function in the default language. For example the HCL has 2 substring functions: substring_by_length_ and substring_by_position_. This makes it easier than calling substr and also calling strpos.
-
Functions dealing with strings have an argument to determine if it should be case_insensitive which makes it clear in the source code.
HCL and Data Types
The HCL uses it's own data types to describe variable data types. This is because javascript's typeof and php's gettype() functions return different values. The function get_type_() returns a HCL_TYPE_xxx value and is the equivalent of typeof and gettype();
The function returns one of the following values:
HCL Capabilities
The HCL is broken down into several "sublibraries". These are "core", "classes" and "dependent".
-
Core: The basis for all HCL functionality. The "Core" capabilities MUST be included for anything in the HCL to work.
-
Classes: These are a series of classes designed to work with the HCL. In most cases they are convience classes that allow you to perform several HCL Core functions easier.
-
Dependent: These are classes and / or functions that only work for either Javascript or PHP. They are not part of the Core or Classes capabilities as those two are and always will be identical between the two languages.
HCL Features
HCL features are specific operations or abilities the HCL can do or not do based on the environment the code is running in. Once such example is Microsecond timestamps. Not all browsers or OSes allow for a timestamp that is accurate to a Microsecond (1/1,000,000 of a second). The hcl_features_() and hcl_feature_() function tells the user if a particular feature is available or not. The function or class documentation will explain what happens if a particular feature is not available and how that will affect it's operation.
About The Source Code
The Javascript version of the source code has been meticulously documented. This is because the overall documentation for the HCL (both Javascript and PHP) is generated from the Javascript source code files. The PHP source code is only documented to help the programmers and not as through as the Javascript code.
In addition:
-
As often as possible HCL functions are used within HCL functions. So for example ceiling_() uses is_numeric_() instead of using native functions like typeof and gettype(). As a result there will be multiple checks when each HCL function is called, which isn't particularly efficient. However this is done to reduce code redundancy. In a later release debug statements will be added to these functions, making it easier to trace back through any of the HCL function calls. See "What the HCL isn't" section for more information.
-
Whenever possible any significant amounts of code taken from a site such as stockoverflow.com are credited with a link to the post they came from.
-
The source code is designed for 5 spaces per tab".
HCL Errors
Most HCL functions will return an error code if the arguments provided are not correct in some way. That error code is HCL_ERROR_VALUE, which by default is the language's null value. Some functions (mostly arrays) provide an option to change the error value returned in case the function might return null as a non-error value.
Array Functions
Math Functions
-
Zero (0) is considered an even value.
String Functions
License
The source code is licensed under the Hutmacher Damn Near Public Domain License.
About this documentation.
To prevent duplication of documentation and possible errors, the documentation for the HCL is included in the javascript source code. The php documentation is generated from the javascript source code as well, with special sections included showing any php specific information about a given function or class